Moai SDK  2.0
MOAITextLabel Class Reference
+ Inheritance diagram for MOAITextLabel:

Function List

clearHighlights
 
getAlignment
 
getGlyphScale
 
getLineSpacing
 
getOverrunRules
 
getRect
 
getSizingRules
 
getStyle
 
getText
 
getTextBounds
 
more
 
nextPage
 
revealAll
 
reserveCurves
 
setAlignment
 
setAutoFlip
 
setBounds
 
setCurve
 
setGlyphScale
 
setHighlight
 
setLineSnap
 
setLineSpacing
 
setOverrunRules
 
setRect
 
setRectLimits
 
setReveal
 
setSpeed
 
setSizingRules
 
setStyle
 
setText
 
setWordBreak
 
setYFlip
 
spool
 
affirmStyle
 
setFont
 
setTextSize
 
- Function List inherited from MOAINode
clearAttrLink
 
clearNodeLink
 
forceUpdate
 
getAttr
 
getAttrLink
 
getNodeState
 
moveAttr
 
scheduleUpdate
 
seekAttr
 
setAttrLink
 
setAttr
 
setNodeLink
 
- Function List inherited from MOAIInstanceEventSource
getListener
 
setListener
 
- Function List inherited from MOAIAction
addChild
 
attach
 
clear
 
defer
 
detach
 
getChildren
 
hasChildren
 
isActive
 
isBusy
 
isDone
 
isPaused
 
pause
 
setAutoStop
 
start
 
stop
 
throttle
 
update
 

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 ().

Constants
MOAITextLabel.BASELINE_JUSTIFY
MOAITextLabel.BOTTOM_JUSTIFY
MOAITextLabel.LEFT_JUSTIFY
MOAITextLabel.CENTER_JUSTIFY
MOAITextLabel.RIGHT_JUSTIFY
MOAITextLabel.TOP_JUSTIFY
MOAITextLabel.WORD_BREAK_NONE
MOAITextLabel.WORD_BREAK_CHAR

Function Documentation

affirmStyle

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
MOAITextLabelself
Returns
MOAITextStyle style
clearHighlights

Removes all highlights currently associated with the text box.


function clearHighlights ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
nil
getAlignment

Returns the alignment of the text.


function getAlignment ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
number hAlign, number vAlign
getGlyphScale

Returns the current glyph scale.


function getGlyphScale ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
number glyphScale
getLineSpacing

Returns the spacing between lines (in pixels).


function getLineSpacing ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
number lineScale
getOverrunRules

Returns the overrun rules.


function getOverrunRules ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
number firstOverrunRule, number overrunRule
getRect

Returns the two-dimensional boundary of the text box (if any).


function getRect ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
number xMin, number yMin, number xMax, number yMax
getSizingRules

Returns the sizing rules.


function getSizingRules ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
number hLayoutSizingRule, number vLayoutSizingRule, number lineSizingRule
getStyle

Returns the style associated with a name or, if no name is given, returns the default style.


function getStyle ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
MOAITextStyle defaultStyle
Note

function getStyle ( MOAITextLabel self, string styleName )

Parameters
MOAITextLabelself
stringstyleName
Returns
MOAITextStyle style
Note
getText

Return the text string.


function getText ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
string text
getTextBounds

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
MOAITextLabelself
numberindex Optional. Index of the first character in the substring.
numbersize Optional. Length of the substring.
Returns
number xMin, number yMin, number xMax, number yMax
more

Returns whether there are additional pages of text below the cursor position that are not visible on the screen.


function more ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
boolean isMore
nextPage

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
MOAITextLabelself
booleanreveal Optional. Default is true
Returns
nil
reserveCurves

Reserves a set of IDs for animation curves to be binding to this text object. See setCurves.


function reserveCurves ( MOAITextLabel self, number nCurves )

Parameters
MOAITextLabelself
numbernCurves
Returns
nil
revealAll

Displays as much text as will fit in the text box.


function revealAll ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
nil
setAlignment

Sets the horizontal and/or vertical alignment of the text in the text box.


function setAlignment ( MOAITextLabel self, number hAlignment, number vAlignment )

Parameters
MOAITextLabelself
numberhAlignment Can be one of LEFT_JUSTIFY, CENTER_JUSTIFY or RIGHT_JUSTIFY.
numbervAlignment Can be one of TOP_JUSTIFY, CENTER_JUSTIFY, BOTTOM_JUSTIFY or BASELINE_JUSTIFY.
Returns
nil
setAutoFlip

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
MOAITextLabelself
booleanautoflip Default value is false.
Returns
nil
setBounds

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
MOAITextLabelself
numberxMin
numberyMin
numberzMin
numberxMax
numberyMax
numberzMax
Returns
nil
Note
Set a the text label's bounding rectagle and enable the limits.

function setBounds ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
nil
Note
Clear the text label's bounding rectangle and disable the limits.
setCurve

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
MOAITextLabelself
numbercurveID The ID of the curve within this text object.
MOAIAnimCurvecurve The MOAIAnimCurve to bind to.
Returns
nil
Note

function setCurve ( MOAITextLabel self )

Parameters
MOAITextLabelself
Returns
nil
Note
setFont

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
MOAITextLabelself
MOAIFontfont
Returns
nil
setGlyphScale

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
MOAITextLabelself
numberglyphScale Optional. Default value is 1.
Returns
number glyphScale
setHighlight

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
MOAITextLabelself
numberindex Index of the first character in the substring.
numbersize Length of the substring.
numberr
numberg
numberb
numbera Optional. Default value is 1.
Returns
nil
Note

function setHighlight ( MOAITextLabel self, number index, number size )

Parameters
MOAITextLabelself
numberindex Index of the first character in the substring.
numbersize Length of the substring.
Returns
nil
Note
setLineSnap

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
MOAITextLabelself
numberhLineSnap Optional.
numbervLineSnap Optional. Default value is hLineSnap.
Returns
nil
setLineSpacing

Sets additional space between lines in text units. '0' uses the default spacing.


function setLineSpacing ( MOAITextLabel self, number lineSpacing )

Parameters
MOAITextLabelself
numberlineSpacing Default value is 0.
Returns
nil
setOverrunRules

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
MOAITextLabelself
numberfirstOverrunRule One of OVERRUN_SPLIT_WORD, OVERRUN_TRUNCATE_WORD, OVERRUN_ABORT_LAYOUT. Default value is OVERRUN_SPLIT_WORD.
numberoverrunRule One of OVERRUN_MOVE_WORD, OVERRUN_SPLIT_WORD, OVERRUN_TRUNCATE_WORD, OVERRUN_ABORT_LAYOUT. Default value is OVERRUN_MOVE_WORD.
Returns
nil
setRect

Sets the rectangular area for this text box.


function setRect ( MOAITextLabel self, number x1, number y1, number x2, number y2 )

Parameters
MOAITextLabelself
numberx1 The X coordinate of the rect's upper-left point.
numbery1 The Y coordinate of the rect's upper-left point.
numberx2 The X coordinate of the rect's lower-right point.
numbery2 The Y coordinate of the rect's lower-right point.
Returns
nil
setRectLimits

Toggles width/height constraints based on the rect.


function setRectLimits ( MOAITextLabel self [, boolean limitWidth, boolean limitHeight ] )

Parameters
MOAITextLabelself
booleanlimitWidth Optional. Limit text to the rect's width. Default value is 'false'.
booleanlimitHeight Optional. Limit text to the rect's height. Default value is 'false'.
Returns
nil
setReveal

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
MOAITextLabelself
numberreveal The number of renderable characters (i.e. not whitespace) to be shown.
Returns
nil
setSizingRules

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
MOAITextLabelself
numberhLayoutSizingRule One of LOGICAL_SIZE or GLYPH_SIZE. Default is LOGICAL_SIZE.
numbervLayoutSizingRule One of LOGICAL_SIZE or GLYPH_SIZE. Default is LOGICAL_SIZE.
numberlineSizingRule One of LOGICAL_SIZE or GLYPH_SIZE. Default is LOGICAL_SIZE.
Returns
nil
setSpeed

Sets the base spool speed used when creating a spooling MOAIAction with the spool() function.


function setSpeed ( MOAITextLabel self, number speed )

Parameters
MOAITextLabelself
numberspeed The base spooling speed.
Returns
nil
setStyle

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
MOAITextLabelself
MOAITextStyledefaultStyle
Returns
nil
Note

function setStyle ( MOAITextLabel self, string styleName, MOAITextStyle style )

Parameters
MOAITextLabelself
stringstyleName
MOAITextStylestyle
Returns
nil
Note
setText

Sets the text string to be displayed by this textbox.


function setText ( MOAITextLabel self, string newStr )

Parameters
MOAITextLabelself
stringnewStr The new text string to be displayed.
Returns
nil
setTextSize

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
MOAITextLabelself
numberpoints The point size to be used by the default style.
numberdpi Optional. The device DPI (dots per inch of device screen). Default value is 72 (points same as pixels).
Returns
nil
setWordBreak

Sets the rule for breaking words across lines.


function setWordBreak ( MOAITextLabel self [, number rule ] )

Parameters
MOAITextLabelself
numberrule Optional. One of MOAITextLabel.WORD_BREAK_NONE, MOAITextLabel.WORD_BREAK_CHAR. Default is MOAITextLabel.WORD_BREAK_NONE.
Returns
nil
setYFlip

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
MOAITextLabelself
booleanyFlip Whether the vertical rendering direction should be inverted.
Returns
nil
spool

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
MOAITextLabelself
Returns
MOAIAction action