Inheritance diagram for MOAITextLabel:
Additional Inherited Members | |
 Function List inherited from MOAIGraphicsPropBase | |
| isVisible | |
| setBillboard | |
| setParent | |
| setScissorRect | |
| setUVTransform | |
| setVisible | |
| Function List inherited from MOAIPartitionHull | |
| getBounds | |
| getDims | |
| getPartition | |
| getPriority | |
| getWorldBounds | |
| inside | |
| setBounds | |
| setExpandForSort | |
| setHitGranularity | |
| setPriority | |
| Function List inherited from MOAITransform | |
| addLoc | |
| addPiv | |
| addRot | |
| addScl | |
| getLoc | |
| getPiv | |
| getRot | |
| getScl | |
| move | |
| moveLoc | |
| movePiv | |
| moveRot | |
| moveScl | |
| seek | |
| seekLoc | |
| seekPiv | |
| seekRot | |
| seekScl | |
| setLoc | |
| setPiv | |
| setRot | |
| setScl | |
| setShearByX | |
| setShearByY | |
| setShearByZ | |
| Function List inherited from MOAITransformBase | |
| getWorldDir | |
| getWorldLoc | |
| getWorldRot | |
| getWorldScl | |
| getWorldXAxis | |
| getWorldYAxis | |
| getWorldZAxis | |
| getWorldXNormal | |
| getWorldYNormal | |
| getWorldZNormal | |
| modelToWorld | |
| setParent | |
| worldToModel | |
| Function List inherited from MOAIColor | |
| getColor | |
| moveColor | |
| seekColor | |
| setColor | |
| setParent | |
Detailed Description
The text box manages styling, laying out and displaying text. You can attach named styles to the text box to be applied to the text using style escapes. You can also inline style escapes to control color. Style escapes may be nested.
To attach a style to a text box use setStyle (). If you provide a name for the style then the style may be applied by name using a style escape. If you do not provide a name then the style will be used as the default style for the text box. The default style is the style that will be used when no style escapes are in effect.
The setFont () and setSize () methods are helpers that operate on the text box's default style. If no default style exists when these methods are called, one will be created.
There are three kinds of text escapes. The first takes the form of <styleName> where 'styleName' is the name of the style you provided via setStyle (). If there is no match for the name then the default style will be used.
The second form of style escape sets text color. It takes the form of <c:XXX> where 'XXX' is a hexadecimal number representing a color value. The hexadecimal number may be have from one up to eight digits, excluding five digit numbers. One and two digit numbers correspond to grayscale values of 4 and 8 bits of precision (16 or 256 levels) respectively. Three and four digit numbers represent RGB and RGBA colors at 4 bit precision. Six digits is RGB at 8 bits of precision. Seven digits is RGBA with 8 bits for RGB and 4 bits for A. Eight digits is RGBA with 8 bits for each component.
The final text escapes ends the current escape. It takes the form of </>. Including any additional text in this kind of escape is an error.
You may escape the '<' symbol itself by using an additional '<'. For example, '<<' will output '<'. '<<test>' will short circuit the style escape and output '<test>' in the displayed text.
When using MOAITextLabel with MOAIFont it's important to understand how and when glyphs are rendered. When you call setText () the text box's style goes to work. The entire string you provide is scanned and a 'style span' is created for each uniquely styled block of text. If you do not use any styles then there will be only one style span.
Once the text style has created style spans for your text, the spans themselves are scanned. Each span must specify a font to be used. All of the characters in the span are 'affirmed' by the font: if the glyphs for the characters have already been ripped then nothing happens. If not, the characters are enqueued by the font to have their glyphs ripped.
Finally, we iterate through all of the fonts used by the text and instruct them to load and render any pending glyphs. If the font is dynamic and has a valid implementation of MOAIFontReader and MOAIDynamicGlyphCache attached to it then the glyphs will be rendered and placed in the cache.
Once the glyphs have been rendered, we know their metrics and (hopefully) have valid textures for them. We can now lay out an actual page of text. This is done by a separate subsystem known as the text designer. The text designer reads the style spans and uses the associated font, color and size information to place the glyphs into a layout.
If the text associated with the textbox doesn't fit, then the textbox will have multiple pages. The only method that deals with pages at this time is nextPage (). Additional methods giving finer control over multi-page text boxes will be provided in a future release.
There are some additional ways you can use the text box to style your text. The current implementation supports left, center and right positioning as well as top, center and bottom positioning. A future implementation will include justification in which words and lines of text will be spaced out to align with the edges of the text box.
You can also attach MOAIAnimCurves to the text box. The animation curves may be used to offset characters in lines of text. Each curve may have any number of keyframes, but only the span between t0 and t1 is used by the text box, regardless of its width. Curves correspond to lines of text. If there are more lines of text than curves, the curves will simply repeat.
Once you've loaded text into the text box you can apply highlight colors. These colors will override any colors specified by style escapes. Highlight spans may be set or cleared using setHighlight (). clearHighlights () will remove all highlights from the text. Highlights will persists from page to page of text, but will be lost if new text is loaded by calling setText ().
|
Function Documentation
|
Returns the textbox's default style. If no default style exists, creates an empty style, sets it as the default and returns it.
function affirmStyle ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- MOAITextStyle style
|
Removes all highlights currently associated with the text box.
function clearHighlights ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- nil
|
Returns the alignment of the text.
function getAlignment ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- number hAlign, number vAlign
|
Returns the current glyph scale.
function getGlyphScale ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- number glyphScale
|
Returns the spacing between lines (in pixels).
function getLineSpacing ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- number lineScale
|
Returns the overrun rules.
function getOverrunRules ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- number firstOverrunRule, number overrunRule
|
Returns the two-dimensional boundary of the text box (if any).
function getRect ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- number xMin, number yMin, number xMax, number yMax
|
Returns the sizing rules.
function getSizingRules ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- number hLayoutSizingRule, number vLayoutSizingRule, number lineSizingRule
|
Returns the style associated with a name or, if no name is given, returns the default style.
function getStyle ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- MOAITextStyle defaultStyle
- Note
function getStyle ( MOAITextLabel self, string styleName )
- Parameters
-
MOAITextLabel self string styleName
- Returns
- MOAITextStyle style
- Note
|
Return the text string.
function getText ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- string text
|
Returns the bounding rectange of a given substring on a single line in the local space of the text box. If 'index' and 'size' are not passed, the bounds for all visible text will be returned.
function getTextBounds ( MOAITextLabel self [, number index, number size ] )
- Parameters
-
MOAITextLabel self number index Optional. Index of the first character in the substring. number size Optional. Length of the substring.
- Returns
- number xMin, number yMin, number xMax, number yMax
|
Returns whether there are additional pages of text below the cursor position that are not visible on the screen.
function more ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- boolean isMore
|
Advances to the next page of text (if any) or wraps to the start of the text (if at end).
function nextPage ( MOAITextLabel self [, boolean reveal ] )
- Parameters
-
MOAITextLabel self boolean reveal Optional. Default is true
- Returns
- nil
|
Reserves a set of IDs for animation curves to be binding to this text object. See setCurves.
function reserveCurves ( MOAITextLabel self, number nCurves )
- Parameters
-
MOAITextLabel self number nCurves
- Returns
- nil
|
Displays as much text as will fit in the text box.
function revealAll ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- nil
|
Sets the horizontal and/or vertical alignment of the text in the text box.
function setAlignment ( MOAITextLabel self, number hAlignment, number vAlignment )
- Parameters
-
MOAITextLabel self number hAlignment Can be one of LEFT_JUSTIFY, CENTER_JUSTIFY or RIGHT_JUSTIFY. number vAlignment Can be one of TOP_JUSTIFY, CENTER_JUSTIFY, BOTTOM_JUSTIFY or BASELINE_JUSTIFY.
- Returns
- nil
|
When autoflip is enabled, the label will be evaluated in screen space during rendering, and flipped vertically to remain 'upright' in the view.
function setAutoFlip ( MOAITextLabel self, boolean autoflip )
- Parameters
-
MOAITextLabel self boolean autoflip Default value is false.
- Returns
- nil
|
Sets or removes a bounding rectangle for the text, specified as the XY planes of the given bounding box. Toggles the rect limits accordingly.
function setBounds ( MOAITextLabel self, number xMin, number yMin, number zMin, number xMax, number yMax, number zMax )
- Parameters
-
MOAITextLabel self number xMin number yMin number zMin number xMax number yMax number zMax
- Returns
- nil
- Note
- Set a the text label's bounding rectagle and enable the limits.
function setBounds ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- nil
- Note
- Clear the text label's bounding rectangle and disable the limits.
|
Binds an animation curve to the text, where the Y value of the curve indicates the text offset, or clears the curves.
function setCurve ( MOAITextLabel self, number curveID, MOAIAnimCurve curve )
- Parameters
-
MOAITextLabel self number curveID The ID of the curve within this text object. MOAIAnimCurve curve The MOAIAnimCurve to bind to.
- Returns
- nil
- Note
function setCurve ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- nil
- Note
|
Sets the font to be used by the textbox's default style. If no default style exists, a default style is created.
function setFont ( MOAITextLabel self, MOAIFont font )
- Parameters
-
MOAITextLabel self MOAIFont font
- Returns
- nil
|
Sets the glyph scale. This is a scalar applied to glyphs as they are positioned in the text box.
function setGlyphScale ( MOAITextLabel self [, number glyphScale ] )
- Parameters
-
MOAITextLabel self number glyphScale Optional. Default value is 1.
- Returns
- number glyphScale
|
Set or clear the highlight color of a sub string in the text. Only affects text displayed on the current page. Highlight will automatically clear when layout or page changes.
function setHighlight ( MOAITextLabel self, number index, number size, number r, number g, number b [, number a ] )
- Parameters
-
MOAITextLabel self number index Index of the first character in the substring. number size Length of the substring. number r number g number b number a Optional. Default value is 1.
- Returns
- nil
- Note
function setHighlight ( MOAITextLabel self, number index, number size )
- Parameters
-
MOAITextLabel self number index Index of the first character in the substring. number size Length of the substring.
- Returns
- nil
- Note
|
Sets the snapping boundary for lines of text. Only applied during layout and in the text label's local space.
function setLineSnap ( MOAITextLabel self [, number hLineSnap, number vLineSnap ] )
- Parameters
-
MOAITextLabel self number hLineSnap Optional. number vLineSnap Optional. Default value is hLineSnap.
- Returns
- nil
|
Sets additional space between lines in text units. '0' uses the default spacing.
function setLineSpacing ( MOAITextLabel self, number lineSpacing )
- Parameters
-
MOAITextLabel self number lineSpacing Default value is 0.
- Returns
- nil
|
Control behavior of text shaper when a token needs to be wrapped. An alternate rule may be set for the first token on a line. OVERRUN_MOVE_WORD will cause the entire token to be moved to the next line. OVERRUN_SPLIT_WORD will split the token across lines. OVERRUN_TRUNCATE_WORD will discard the remaining characters in the token. OVERRUN_ABORT_LAYOUT will back up to the start of the token and stop the layout. OVERRUN_MOVE_WORD is not permitted as the rule for the line's first token. If the first token doesn't fit on current line, it will not fit on the next line and so on.
function setOverrunRule ( MOAITextLabel self, number firstOverrunRule, number overrunRule )
- Parameters
-
MOAITextLabel self number firstOverrunRule One of OVERRUN_SPLIT_WORD, OVERRUN_TRUNCATE_WORD, OVERRUN_ABORT_LAYOUT. Default value is OVERRUN_SPLIT_WORD. number overrunRule One of OVERRUN_MOVE_WORD, OVERRUN_SPLIT_WORD, OVERRUN_TRUNCATE_WORD, OVERRUN_ABORT_LAYOUT. Default value is OVERRUN_MOVE_WORD.
- Returns
- nil
|
Sets the rectangular area for this text box.
function setRect ( MOAITextLabel self, number x1, number y1, number x2, number y2 )
- Parameters
-
MOAITextLabel self number x1 The X coordinate of the rect's upper-left point. number y1 The Y coordinate of the rect's upper-left point. number x2 The X coordinate of the rect's lower-right point. number y2 The Y coordinate of the rect's lower-right point.
- Returns
- nil
|
Toggles width/height constraints based on the rect.
function setRectLimits ( MOAITextLabel self [, boolean limitWidth, boolean limitHeight ] )
- Parameters
-
MOAITextLabel self boolean limitWidth Optional. Limit text to the rect's width. Default value is 'false'. boolean limitHeight Optional. Limit text to the rect's height. Default value is 'false'.
- Returns
- nil
|
Sets the number of renderable characters to be shown. Can range from 0 to any value; values greater than the number of renderable characters in the current text will be ignored.
function setReveal ( MOAITextLabel self, number reveal )
- Parameters
-
MOAITextLabel self number reveal The number of renderable characters (i.e. not whitespace) to be shown.
- Returns
- nil
|
The sizing rules are used to determine the boundaries of each line for layout and alignment purposes. The H and V layout sizing rules determine whether the layout is based on the tight-fitting glyph boundaries or the (possibly) looser fitting 'logical' bounds (i.e. the bounds specified by the type face, allowing for full ascent and descent). The line sizing rule determines whether lines are spaced from logical or glyph bounds. Note that these rules do not affect the spacing of glyphs as they are laid out within a line, but they do affect the spacing of lines.
function setSizingRule ( MOAITextLabel self, number hLayoutSizingRule, number vLayoutSizingRule, number lineSizingRule )
- Parameters
-
MOAITextLabel self number hLayoutSizingRule One of LOGICAL_SIZE or GLYPH_SIZE. Default is LOGICAL_SIZE. number vLayoutSizingRule One of LOGICAL_SIZE or GLYPH_SIZE. Default is LOGICAL_SIZE. number lineSizingRule One of LOGICAL_SIZE or GLYPH_SIZE. Default is LOGICAL_SIZE.
- Returns
- nil
|
Sets the base spool speed used when creating a spooling MOAIAction with the spool() function.
function setSpeed ( MOAITextLabel self, number speed )
- Parameters
-
MOAITextLabel self number speed The base spooling speed.
- Returns
- nil
|
Attaches a style to the textbox and associates a name with it. If no name is given, sets the default style.
function setStyle ( MOAITextLabel self, MOAITextStyle defaultStyle )
- Parameters
-
MOAITextLabel self MOAITextStyle defaultStyle
- Returns
- nil
- Note
function setStyle ( MOAITextLabel self, string styleName, MOAITextStyle style )
- Parameters
-
MOAITextLabel self string styleName MOAITextStyle style
- Returns
- nil
- Note
|
Sets the text string to be displayed by this textbox.
function setText ( MOAITextLabel self, string newStr )
- Parameters
-
MOAITextLabel self string newStr The new text string to be displayed.
- Returns
- nil
|
Sets the size to be used by the textbox's default style. If no default style exists, a default style is created.
function setTextSize ( MOAITextLabel self, number points [, number dpi ] )
- Parameters
-
MOAITextLabel self number points The point size to be used by the default style. number dpi Optional. The device DPI (dots per inch of device screen). Default value is 72 (points same as pixels).
- Returns
- nil
|
Sets the rule for breaking words across lines.
function setWordBreak ( MOAITextLabel self [, number rule ] )
- Parameters
-
MOAITextLabel self number rule Optional. One of MOAITextLabel.WORD_BREAK_NONE, MOAITextLabel.WORD_BREAK_CHAR. Default is MOAITextLabel.WORD_BREAK_NONE.
- Returns
- nil
|
Sets the rendering direction for the text. Default assumes a window style screen space (positive Y moves down the screen). Set to true to render text for world style coordinate systems (positive Y moves up the screen).
function setYFlip ( MOAITextLabel self, boolean yFlip )
- Parameters
-
MOAITextLabel self boolean yFlip Whether the vertical rendering direction should be inverted.
- Returns
- nil
|
Creates a new MOAIAction which when run has the effect of increasing the amount of characters revealed from 0 to the length of the string currently set. The spool action is automatically added to the root of the action tree, but may be reparented or stopped by the developer. This function also automatically sets the current number of revealed characters to 0 (i.e. MOAITextLabel:setReveal(0)).
function spool ( MOAITextLabel self )
- Parameters
-
MOAITextLabel self
- Returns
- MOAIAction action
