SpriteText Class Reference

Inherits IUseCamera.

List of all members.

Public Types
enum	Anchor_Pos
enum	Alignment_Type
	How the text will be aligned. More...
Public Member Functions
int	GetDisplayLineCount (int charIndex, out int charLine, out int lineStart, out int lineEnd)
	Returns the number of lines actually being displayed, as opposed to the number of lines in the string assigned to the object. In other words, if word-wrapping is being used, the number of actual lines displayed may be more than the number of lines in the actual string. It also stores the line number of the character at the specified index in the string.
int	GetDisplayLineCount ()
	Returns the number of lines actually being displayed, as opposed to the number of lines in the string assigned to the object. In other words, if word-wrapping is being used, the number of actual lines displayed may be more than the number of lines in the actual string.
int	PlainIndexToDisplayIndex (int plainCharIndex)
	Converts a character index in the plain text string to a corresponding index in the display string.
int	DisplayIndexToPlainIndex (int dispCharIndex)
	Converts a character index in the display text string to a corresponding index in the plain text string.
void	Unclip ()
	Removes any clipping that is being applied to the text object.
void	Delete ()
	Call Delete() before destroying this component or the GameObject to which it is attached. Memory leaks can ensue otherwise.
virtual void	Copy (SpriteText s)
	Duplicates the settings of another SpriteText object.
void	SetColor (Color c)
	Sets the text's color to the specified color. NOTE: Will not override color tags in the text itself.
void	SetCharacterSize (float size)
	Sets the size (height) of the text such that a capital character that extends from the baseline to the absolute top of the line will be the specified height in world units. All other characters will be sized proportionately. If called while set to pixel perfect, pixel-perfect will be automatically disabled.
void	SetLineSpacing (float spacing)
	Sets the spacing between lines as a percentage of the character size. i.e. a value of 1.1 means 10% of the height of a full-height character will be placed between lines.
void	SetFont (TextAsset newFont, Material fontMaterial)
	Changes the font to be used for this text object.
void	SetFont (SpriteFont newFont, Material fontMaterial)
	Changes the font to be used for this text object.
void	UpdateCamera ()
	Updates any camera-dependent settings, such as the calculated pixel-perfect size. Use this with BroadcastMessage() to do bulk re-calculation of object sizes whenever your screensize/resolution changes at runtime.
void	SetCamera ()
	A no-argument version of SetCamera() that simply re-assigns the same camera to the object, forcing it to recalculate all camera-dependent calculations.
void	SetCamera (Camera c)
	Sets the camera to use when calculating a pixel-perfect character size.
virtual void	Hide (bool tf)
	Hides or displays the text by disabling/enabling the mesh renderer component.
bool	IsHidden ()
	Returns whether the text is currently set to be hidden (whether its mesh renderer component is enabled).
Vector3	GetInsertionPointPos (int charIndex)
	Returns the position, in world space, of the insertion point relative to a specified character (specified by index). The position returned is at the left edge of, and the baseline of, the specified character.
Vector3	GetNearestInsertionPointPos (Vector3 point, ref int insertionPt)
	Returns both the world-space position of the insertion point most nearly matching the specified point, as well as the index of the character to the left of which the insertion point corresponds.
int	GetNearestInsertionPoint (Vector3 point)
	Returns both the world-space position of the insertion point most nearly matching the specified point, as well as the index of the character to the left of which the insertion point corresponds.
Vector3[]	GetVertices ()
	Returns a reference to the text's vertices.
Vector3	GetCenterPoint ()
	Gets the center point of the text's extents in local space.
float	GetWidth (string s)
	Returns the width, in world units, of the specified string were it to be rendered using the current font and settings. NOTE: Assumes the string is a single line.
float	GetScreenWidth (string s)
	Returns the width, in screen pixels, of the specified string were it to be rendered using the current font and settings. NOTE: Assumes the string is a single line.
void	SetAnchor (Anchor_Pos a)
	Sets the anchor type to use. See Anchor_Pos.
void	SetAlignment (Alignment_Type a)
	Sets the alignment of the text (left, right, center).
Vector2	PixelSpaceToUVSpace (Vector2 xy)
	Converts pixel-space values to UV-space scalar values according to the currently assigned material. NOTE: This is for converting widths and heights-not coordinates (which have reversed Y-coordinates). For coordinates, use PixelCoordToUVCoord()!
Vector2	PixelSpaceToUVSpace (int x, int y)
	Converts pixel-space values to UV-space scalar values according to the currently assigned material. NOTE: This is for converting widths and heights-not coordinates (which have reversed Y-coordinates). For coordinates, use PixelCoordToUVCoord()!
Vector2	PixelCoordToUVCoord (Vector2 xy)
	Converts pixel coordinates to UV coordinates according to the currently assigned material. NOTE: This is for converting coordinates and will reverse the Y component accordingly. For converting widths and heights, use PixelSpaceToUVSpace()!
Vector2	PixelCoordToUVCoord (int x, int y)
	Converts pixel coordinates to UV coordinates according to the currently assigned material. NOTE: This is for converting coordinates and will reverse the Y component accordingly. For converting widths and heights, use PixelSpaceToUVSpace()!
Public Attributes
string	text = "Hello World"
	The (decorated) text the object is to contain. NOTE: This is only for use in the inspector at edit time. The ".Text" or ".PlainText" properties should be used in script at runtime.
float	offsetZ
	The distance the text is to be offset along the local Z-axis from the GameObject's center.
float	characterSize = 1f
	The size, in world units, of a full-height character. All other characters will be sized proportionately.
float	characterSpacing = 1f
	An adjustable factor by which you can increase/decrease the spacing between characters. A value of 1.0 will space characters exactly as described by the font. Decreasing this value will place the characters closer together, while increasing it will place them farther apart.
float	lineSpacing = 1.1f
	The distance from one line to the next as a percentage of characterSize. Defaults to a distance that is 1.1 times the height of a character. This has the effect of creating a gap between lines that is 10% the height of a line.
Anchor_Pos	anchor = Anchor_Pos.Upper_Left
	The position of the center of the GameObject relative to the text.
Alignment_Type	alignment
	How the text is to be aligned.
int	tabSize = 4
	The number of space characters which are produced by a tab character.
TextAsset	font
	Text asset that defines the font to be used.
Color	color = Color.white
	The color to be used by all of the text's vertices. This can be used to color, highlight, or fade the text. Be sure to use a vertex-colored shader for this to have an effect.
bool	pixelPerfect = false
	Automatically sizes the text so that it will display pixel-perfect on-screen. NOTE: If you change the orthographic size of the camera or the distance between the text and a perspective camera, call SetCamera() to make the text pixel-perfect again.
float	maxWidth = 0
	When set to a value over 0, if the multiline setting is true, then the content of the SpriteText object will be word-wrapped when a line reaches the specified maximum width (specified in local units), otherwise the text displayed will be truncated and "..." will be appended. NOTE: The actual text contents are preserved and only the display string is truncated.
bool	multiline = true
	When set to true, the text object will allow multi-line content. This also enables word-wrapping when the maxWidth setting is set to a non-zero value. If multiline is false, then a non-zero maxWidth setting will cause text that exceeds the maxWidth to be truncated and have "..." appended. NOTE: The actual text contents are preserved and only the display string is truncated.
bool	dynamicLength = false
	When true, this setting tells the script that it should optimize its behavior on the assumption that its contents will change size frequently. When false, it will be optimized on the assumption that its length will remain the same for most, if not all, of the time.
bool	removeUnsupportedCharacters = true
	When true, any unsupported characters in the string assigned to this object at runtime will be removed from the string. NOTE: Using this on large amounts of text may have an adverse impact on performance.
bool	parseColorTags = true
	If set to false, color tags will not be parsed out of the text.
bool	password = false
	When set to true, all text in this control will be masked using the specified maskingCharacter.
string	maskingCharacter = "*"
	Holds the character to be used to mask password text. Defaults to asterisk (*).
const string	colorTag = "[#"
	Character that must be placed on either side of a color value in a string to indicate a change of text color.
bool	hideAtStart = false
	Whether the text will be hidden when it starts.
bool	persistent = false
	This must be set to true at design time for the object to survive loading a new level.
bool	ignoreClipping = false
	When true, the text will not be clipped.
Properties
Color	Color [get, set]
	Accessor for the object's current overall color tint.
Camera	RenderCamera [get, set]
	Accessor for the camera that will be used to render this object. Use this to ensure the object is properly configured for the specific camera that will render it.
bool	Persistent [get, set]
	Marks the object to be persistent between scenes (it will not be destroyed when a new scene is loaded). Once this is set to true, it cannot be undone.
string	Text [get, set]
	Sets and retrieves the full, decorated text string.
string	PlainText [get]
	Retrieves the plain (undecorated) text string.
string	DisplayString [get]
	The actual string being displayed (includes line feed characters, etc, generated from any word-wrapping).
Rect3D	ClippingRect [get, set]
	The rect against which the text should be clipped. The text will be immediately clipped by this rect when set. When setting, the rect should be in world space.
bool	Clipped [get, set]
	Accessor for whether the text is to be clipped by any already-specified clipping rect.
float	BaseHeight [get]
	Returns the distance from the baseline to the top of a line, in local space units.
float	LineSpan [get]
	The distance, in local space units, from the top of one line to the top of the next.
Vector3	TopLeft [get]
	Returns the position of the top-left corner of the text's extremities.
Vector3	BottomRight [get]
	Returns the position of the bottom-right corner of the text's extremities.
float	TotalWidth [get]
	The current total width of the text (widest line) in local units.
float	TotalScreenWidth [get]
	Returns the current total width of the text (widest line) in screen pixels.
Vector2	PixelSize [get]
	Gets the width and height of the text area in pixels as it appears on-screen.
Anchor_Pos	Anchor [get, set]
	Accessor for the object's anchor method.
float	CharacterSpacing [get, set]
	An adjustable factor by which you can increase/decrease the spacing between characters. A value of 1.0 will space characters exactly as described by the font. Decreasing this value will place the characters closer together, while increasing it will place them farther apart.

---

Detailed Description

A class that impelements sprite-based text.

---

Member Enumeration Documentation

enum SpriteText::Alignment_Type

How the text will be aligned.

enum SpriteText::Anchor_Pos

Which point of the text shares the position of the Transform.

---

Member Function Documentation

virtual void SpriteText.Copy

(

SpriteText

s

)

[virtual]

Duplicates the settings of another SpriteText object.

Parameters:

s

The SpriteText object to be copied.

void SpriteText.Delete

(

)

Call Delete() before destroying this component or the GameObject to which it is attached. Memory leaks can ensue otherwise.

int SpriteText.DisplayIndexToPlainIndex

(

int

dispCharIndex

)

Converts a character index in the display text string to a corresponding index in the plain text string.

Parameters:

plainCharIndex

The index in the display string to be converted.

Returns:

The index in the plain text string that corresponds to the provided index in the display text string.

Vector3 SpriteText.GetCenterPoint

(

)

Gets the center point of the text's extents in local space.

Returns:

The center point of the text extents.

int SpriteText.GetDisplayLineCount

(

)

Returns the number of lines actually being displayed, as opposed to the number of lines in the string assigned to the object. In other words, if word-wrapping is being used, the number of actual lines displayed may be more than the number of lines in the actual string.

Returns:

The number of lines actually being displayed. NOTE: This value will never be less than 1.

int SpriteText.GetDisplayLineCount	(	int	charIndex,
		out int	charLine,
		out int	lineStart,
		out int	lineEnd
	)

Returns the number of lines actually being displayed, as opposed to the number of lines in the string assigned to the object. In other words, if word-wrapping is being used, the number of actual lines displayed may be more than the number of lines in the actual string. It also stores the line number of the character at the specified index in the string.

Parameters:

	charIndex	The index of the character sought.
	charLine	OUT: The 1-based line number on which the character at charIndex sits.
	lineStart	OUT: The index of the first character on the same line as the character at the specified index.
	lineEnd	OUT: The index of the last character on the same line as the character at the specified index (excludes ending newline character).

Returns:

The number of lines actually being displayed.

Vector3 SpriteText.GetInsertionPointPos

(

int

charIndex

)

Returns the position, in world space, of the insertion point relative to a specified character (specified by index). The position returned is at the left edge of, and the baseline of, the specified character.

Parameters:

charIndex

The 0-based index of the character to the right of where you want an insertion point. 0 indicates the very beginning, and an index equal to the string's length indicates an insertion point at the very end of the string.

Returns:

Returns a point at the left edge of, and the baseline of, the specified character.

int SpriteText.GetNearestInsertionPoint

(

Vector3

point

)

Returns both the world-space position of the insertion point most nearly matching the specified point, as well as the index of the character to the left of which the insertion point corresponds.

Parameters:

point

A point, in world space, from which you want to find the nearest insertion point.

Returns:

The index of the character to the right of where the insertion point will be. If the insertion point is at the end of the string, this value will be one greater than the index of the last character.

Vector3 SpriteText.GetNearestInsertionPointPos	(	Vector3	point,
		ref int	insertionPt
	)

Returns both the world-space position of the insertion point most nearly matching the specified point, as well as the index of the character to the left of which the insertion point corresponds.

Parameters:

	point	A point, in world space, from which you want to find the nearest insertion point.
	insertionPt	OUT: Will hold the index of the character to the left of which the insertion point will be. If the insertion point is at the end of the string, this value will be one greater than the index of the last character.

Returns:

The position, in world space, of the desired insertion point.

float SpriteText.GetScreenWidth

(

string

s

)

Returns the width, in screen pixels, of the specified string were it to be rendered using the current font and settings. NOTE: Assumes the string is a single line.

Parameters:

s

The string to measure.

Returns:

The width, in world units.

Vector3 [] SpriteText.GetVertices

(

)

Returns a reference to the text's vertices.

Returns:

A reference to the sprite's vertices.

float SpriteText.GetWidth

(

string

s

)

Returns the width, in world units, of the specified string were it to be rendered using the current font and settings. NOTE: Assumes the string is a single line.

Parameters:

s

The string to measure.

Returns:

The width, in world units.

virtual void SpriteText.Hide

(

bool

tf

)

[virtual]

Hides or displays the text by disabling/enabling the mesh renderer component.

Parameters:

tf

When true, the text is hidden, when false, the text will be displayed.

bool SpriteText.IsHidden

(

)

Returns whether the text is currently set to be hidden (whether its mesh renderer component is enabled).

Returns:

True when hidden, false when set to be displayed.

Vector2 SpriteText.PixelCoordToUVCoord	(	int	x,
		int	y
	)

Converts pixel coordinates to UV coordinates according to the currently assigned material. NOTE: This is for converting coordinates and will reverse the Y component accordingly. For converting widths and heights, use PixelSpaceToUVSpace()!

Parameters:

	x	The x-coordinate to convert.
	y	The y-coordinate to convert.

Returns:

The coordinates converted to UV coordinates.

Vector2 SpriteText.PixelCoordToUVCoord

(

Vector2

xy

)

Converts pixel coordinates to UV coordinates according to the currently assigned material. NOTE: This is for converting coordinates and will reverse the Y component accordingly. For converting widths and heights, use PixelSpaceToUVSpace()!

Parameters:

xy

The coordinates to convert.

Returns:

The coordinates converted to UV coordinates.

Vector2 SpriteText.PixelSpaceToUVSpace	(	int	x,
		int	y
	)

Converts pixel-space values to UV-space scalar values according to the currently assigned material. NOTE: This is for converting widths and heights-not coordinates (which have reversed Y-coordinates). For coordinates, use PixelCoordToUVCoord()!

Parameters:

	x	The X-value to convert.
	y	The Y-value to convert.

Returns:

The values converted to UV space.

Vector2 SpriteText.PixelSpaceToUVSpace

(

Vector2

xy

)

Converts pixel-space values to UV-space scalar values according to the currently assigned material. NOTE: This is for converting widths and heights-not coordinates (which have reversed Y-coordinates). For coordinates, use PixelCoordToUVCoord()!

Parameters:

xy

The values to convert.

Returns:

The values converted to UV space.

int SpriteText.PlainIndexToDisplayIndex

(

int

plainCharIndex

)

Converts a character index in the plain text string to a corresponding index in the display string.

Parameters:

plainCharIndex

The index in the plain string to be converted.

Returns:

The index in the display string that corresponds to the provided index in the plain text string.

void SpriteText.SetAlignment

(

Alignment_Type

a

)

Sets the alignment of the text (left, right, center).

Parameters:

a

The alignment to use.

void SpriteText.SetAnchor

(

Anchor_Pos

a

)

Sets the anchor type to use. See Anchor_Pos.

Parameters:

a

The anchor method to use.

void SpriteText.SetCamera

(

Camera

c

)

Sets the camera to use when calculating a pixel-perfect character size.

Parameters:

c

void SpriteText.SetCamera

(

)

A no-argument version of SetCamera() that simply re-assigns the same camera to the object, forcing it to recalculate all camera-dependent calculations.

void SpriteText.SetCharacterSize

(

float

size

)

Sets the size (height) of the text such that a capital character that extends from the baseline to the absolute top of the line will be the specified height in world units. All other characters will be sized proportionately. If called while set to pixel perfect, pixel-perfect will be automatically disabled.

Parameters:

size

The size of a full-height character, in world units.

void SpriteText.SetColor

(

Color

c

)

Sets the text's color to the specified color. NOTE: Will not override color tags in the text itself.

Parameters:

c

Color to shade the text.

void SpriteText.SetFont	(	SpriteFont	newFont,
		Material	fontMaterial
	)

Changes the font to be used for this text object.

Parameters:

	newFont	Reference to the SpriteFont to be used for this text object.
	fontMaterial	The material to use for the new font.

void SpriteText.SetFont	(	TextAsset	newFont,
		Material	fontMaterial
	)

Changes the font to be used for this text object.

Parameters:

	newFont	The TextAsset that defines the font to be used.
	fontMaterial	The material to use for the new font.

void SpriteText.SetLineSpacing

(

float

spacing

)

Sets the spacing between lines as a percentage of the character size. i.e. a value of 1.1 means 10% of the height of a full-height character will be placed between lines.

Parameters:

spacing

Percentage of the line height to place between lines.

void SpriteText.Unclip

(

)

Removes any clipping that is being applied to the text object.

void SpriteText.UpdateCamera

(

)

Updates any camera-dependent settings, such as the calculated pixel-perfect size. Use this with BroadcastMessage() to do bulk re-calculation of object sizes whenever your screensize/resolution changes at runtime.

---

Member Data Documentation

Alignment_Type SpriteText.alignment

How the text is to be aligned.

Anchor_Pos SpriteText.anchor = Anchor_Pos.Upper_Left

The position of the center of the GameObject relative to the text.

float SpriteText.characterSize = 1f

The size, in world units, of a full-height character. All other characters will be sized proportionately.

float SpriteText.characterSpacing = 1f

An adjustable factor by which you can increase/decrease the spacing between characters. A value of 1.0 will space characters exactly as described by the font. Decreasing this value will place the characters closer together, while increasing it will place them farther apart.

Color SpriteText.color = Color.white

The color to be used by all of the text's vertices. This can be used to color, highlight, or fade the text. Be sure to use a vertex-colored shader for this to have an effect.

const string SpriteText.colorTag = "[#"

Character that must be placed on either side of a color value in a string to indicate a change of text color.

bool SpriteText.dynamicLength = false

When true, this setting tells the script that it should optimize its behavior on the assumption that its contents will change size frequently. When false, it will be optimized on the assumption that its length will remain the same for most, if not all, of the time.

TextAsset SpriteText.font

Text asset that defines the font to be used.

bool SpriteText.hideAtStart = false

Whether the text will be hidden when it starts.

bool SpriteText.ignoreClipping = false

When true, the text will not be clipped.

float SpriteText.lineSpacing = 1.1f

The distance from one line to the next as a percentage of characterSize. Defaults to a distance that is 1.1 times the height of a character. This has the effect of creating a gap between lines that is 10% the height of a line.

string SpriteText.maskingCharacter = "*"

Holds the character to be used to mask password text. Defaults to asterisk (*).

float SpriteText.maxWidth = 0

When set to a value over 0, if the multiline setting is true, then the content of the SpriteText object will be word-wrapped when a line reaches the specified maximum width (specified in local units), otherwise the text displayed will be truncated and "..." will be appended. NOTE: The actual text contents are preserved and only the display string is truncated.

bool SpriteText.multiline = true

When set to true, the text object will allow multi-line content. This also enables word-wrapping when the maxWidth setting is set to a non-zero value. If multiline is false, then a non-zero maxWidth setting will cause text that exceeds the maxWidth to be truncated and have "..." appended. NOTE: The actual text contents are preserved and only the display string is truncated.

float SpriteText.offsetZ

The distance the text is to be offset along the local Z-axis from the GameObject's center.

bool SpriteText.parseColorTags = true

If set to false, color tags will not be parsed out of the text.

bool SpriteText.password = false

When set to true, all text in this control will be masked using the specified maskingCharacter.

bool SpriteText.persistent = false

This must be set to true at design time for the object to survive loading a new level.

bool SpriteText.pixelPerfect = false

Automatically sizes the text so that it will display pixel-perfect on-screen. NOTE: If you change the orthographic size of the camera or the distance between the text and a perspective camera, call SetCamera() to make the text pixel-perfect again.

bool SpriteText.removeUnsupportedCharacters = true

When true, any unsupported characters in the string assigned to this object at runtime will be removed from the string. NOTE: Using this on large amounts of text may have an adverse impact on performance.

int SpriteText.tabSize = 4

The number of space characters which are produced by a tab character.

string SpriteText.text = "Hello World"

The (decorated) text the object is to contain. NOTE: This is only for use in the inspector at edit time. The ".Text" or ".PlainText" properties should be used in script at runtime.

---

Property Documentation

Anchor_Pos SpriteText.Anchor [get, set]

Accessor for the object's anchor method.

float SpriteText.BaseHeight [get]

Returns the distance from the baseline to the top of a line, in local space units.

Vector3 SpriteText.BottomRight [get]

Returns the position of the bottom-right corner of the text's extremities.

float SpriteText.CharacterSpacing [get, set]

An adjustable factor by which you can increase/decrease the spacing between characters. A value of 1.0 will space characters exactly as described by the font. Decreasing this value will place the characters closer together, while increasing it will place them farther apart.

bool SpriteText.Clipped [get, set]

Accessor for whether the text is to be clipped by any already-specified clipping rect.

Rect3D SpriteText.ClippingRect [get, set]

The rect against which the text should be clipped. The text will be immediately clipped by this rect when set. When setting, the rect should be in world space.

Color SpriteText.Color [get, set]

Accessor for the object's current overall color tint.

string SpriteText.DisplayString [get]

The actual string being displayed (includes line feed characters, etc, generated from any word-wrapping).

float SpriteText.LineSpan [get]

The distance, in local space units, from the top of one line to the top of the next.

bool SpriteText.Persistent [get, set]

Marks the object to be persistent between scenes (it will not be destroyed when a new scene is loaded). Once this is set to true, it cannot be undone.

Vector2 SpriteText.PixelSize [get]

Gets the width and height of the text area in pixels as it appears on-screen.

string SpriteText.PlainText [get]

Retrieves the plain (undecorated) text string.

Camera SpriteText.RenderCamera [get, set]

Accessor for the camera that will be used to render this object. Use this to ensure the object is properly configured for the specific camera that will render it.

string SpriteText.Text [get, set]

Sets and retrieves the full, decorated text string.

Vector3 SpriteText.TopLeft [get]

Returns the position of the top-left corner of the text's extremities.

float SpriteText.TotalScreenWidth [get]

Returns the current total width of the text (widest line) in screen pixels.

float SpriteText.TotalWidth [get]

The current total width of the text (widest line) in local units.

---

The documentation for this class was generated from the following file:

• SpriteText.cs