Inheritance diagram for MOAITextBox:

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 MOAITextBox 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 MOAIGlyphCache 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

MOAITextBox.LEFT_JUSTIFY

MOAITextBox.CENTER_JUSTIFY

MOAITextBox.RIGHT_JUSTIFY

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 ( MOAITextBox self )

Parameters:

self	( MOAITextBox )

Returns:: style ( MOAITextStyle )

clearHighlights

Removes all highlights currently associated with the text box.

function clearHighlights ( MOAITextBox self )

Parameters:

self	( MOAITextBox )

Returns:: nil

getAlignment

Returns the alignment of the text.

function getAlignment ( MOAITextBox self )

Parameters:

self	( MOAITextBox )

Returns:: hAlign ( number ), vAlign ( number )

getGlyphScale

Returns the current glyph scale.

function getGlyphScale ( MOAITextBox self )

Parameters:

self	( MOAITextBox )

Returns:: glyphScale ( number )

getLineSpacing

Returns the spacing between lines (in pixels).

function getLineSpacing ( MOAITextBox self )

Parameters:

self	( MOAITextBox )

Returns:: lineScale ( number )

getRect

Returns the two-dimensional boundary of the text box.

function getRect ( MOAITextBox self )

Parameters:

self	( MOAITextBox )

Returns:: xMin ( number ), yMin ( number ), xMax ( number ), yMax ( number )

getStringBounds

Returns the bounding rectangle of a given substring on a single line in the local space of the text box.

function getStringBounds ( MOAITextBox self, number index, number size )

Parameters:

self	( MOAITextBox )
index	( number ) Index of the first character in the substring.
size	( number ) Length of the substring.

Returns:: xMin ( number ), yMin ( number ), xMax ( number ), yMax ( number )

getStyle

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

function getStyle ( MOAITextBox self )

Parameters:

self	( MOAITextBox )

Returns:: defaultStyle ( MOAITextStyle )

Note:

function getStyle ( MOAITextBox self, string styleName )

Parameters:

self	( MOAITextBox )
styleName	( string )

Returns:: style ( MOAITextStyle )

Note:

more

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

function more ( MOAITextBox self )

Parameters:

self	( MOAITextBox )

Returns:: isMore ( boolean )

function nextPage ( MOAITextBox self [, boolean reveal ] )

Parameters:

self	( MOAITextBox )
reveal	( boolean ) 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 ( MOAITextBox self, number nCurves )

Parameters:

self	( MOAITextBox )
nCurves	( number )

Returns:: nil

revealAll

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

function revealAll ( MOAITextBox self )

Parameters:

self	( MOAITextBox )

Returns:: nil

setAlignment

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

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

Parameters:

self	( MOAITextBox )
hAlignment	( number ) Can be one of LEFT_JUSTIFY, CENTER_JUSTIFY or RIGHT_JUSTIFY.
vAlignment	( number ) Can be one of LEFT_JUSTIFY, CENTER_JUSTIFY or RIGHT_JUSTIFY.

Returns:: nil

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 ( MOAITextBox self, number curveID, MOAIAnimCurve curve )

Parameters:

self	( MOAITextBox )
curveID	( number ) The ID of the curve within this text object.
curve	( MOAIAnimCurve ) The MOAIAnimCurve to bind to.

Returns:: nil

Note:

function setCurve ( MOAITextBox self )

Parameters:

self	( MOAITextBox )

Returns:

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 ( MOAITextBox self, MOAIFont font )

Parameters:

self	( MOAITextBox )
font	( MOAIFont )

Returns:: nil

setGlyphScale

Sets the glyph scale. This is a scalar applied to glyphs as they are positioned in the text box.

function setGlyphScale ( MOAITextBox self [, number glyphScale ] )

Parameters:

self	( MOAITextBox )
glyphScale	( number ) Optional. Default value is 1.

Returns:: glyphScale ( number )

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 ( MOAITextBox self, number index, number size, number r, number g, number b [, number a ] )

Parameters:

self	( MOAITextBox )
index	( number ) Index of the first character in the substring.
size	( number ) Length of the substring.
r	( number )
g	( number )
b	( number )
a	( number ) Optional. Default value is 1.

Returns:: nil

Note:

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

Parameters:

self	( MOAITextBox )
index	( number ) Index of the first character in the substring.
size	( number ) Length of the substring.

Returns:: nil

Note:

setLineSpacing

Sets additional space between lines in text units. '0' uses the default spacing. Values must be positive.

function setLineSpacing ( MOAITextBox self, number lineSpacing )

Parameters:

self	( MOAITextBox )
lineSpacing	( number ) Default value is 0.

Returns:: nil

setRect

Sets the rectangular area for this text box.

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

Parameters:

self	( MOAITextBox )
x1	( number ) The X coordinate of the rect's upper-left point.
y1	( number ) The Y coordinate of the rect's upper-left point.
x2	( number ) The X coordinate of the rect's lower-right point.
y2	( number ) The Y coordinate of the rect's lower-right point.

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 ( MOAITextBox self, number reveal )

Parameters:

self	( MOAITextBox )
reveal	( number ) The number of renderable characters (i.e. not whitespace) to be shown.

Returns:: nil

setSnapToViewportScale

If set to true text positions will snap to integers according to the viewport scale. Default value is true.

function setSnapToViewportScale ( MOAITextBox self, boolean snap )

Parameters:

self	( MOAITextBox )
snap	( boolean ) Whether text positions should snap to viewport scale

Returns:: nil

setSpeed

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

function setSpeed ( MOAITextBox self, number speed )

Parameters:

self	( MOAITextBox )
speed	( number ) The base spooling speed.

Returns:: nil

setString

Sets the text string to be displayed by this textbox.

function setString ( MOAITextBox self, string newStr )

Parameters:

self	( MOAITextBox )
newStr	( string ) The new text string to be displayed.

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 ( MOAITextBox self, MOAITextStyle defaultStyle )

Parameters:

self	( MOAITextBox )
defaultStyle	( MOAITextStyle )

Returns:: nil

Note:

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

Parameters:

self	( MOAITextBox )
styleName	( string )
style	( MOAITextStyle )

Returns:: nil

Note:

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 ( MOAITextBox self, number points [, number dpi ] )

Parameters:

self	( MOAITextBox )
points	( number ) The point size to be used by the default style.
dpi	( number ) 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 ( MOAITextBox self [, number rule ] )

Parameters:

self	( MOAITextBox )
rule	( number ) Optional. One of MOAITextBox.WORD_BREAK_NONE, MOAITextBox.WORD_BREAK_CHAR. Default is MOAITextBox.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 ( MOAITextBox self, boolean yFlip )

Parameters:

self	( MOAITextBox )
yFlip	( boolean ) 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. MOAITextBox:setReveal(0)).

function spool ( MOAITextBox self, number yFlip )

Parameters:

self	( MOAITextBox )
yFlip	( number ) Whether the vertical rendering direction should be inverted.

Returns:: action ( MOAIAction )

Function List
	clearHighlights
	getAlignment
	getGlyphScale
	getLineSpacing
	getRect
	getStringBounds
	getStyle
	more
	nextPage
	revealAll
	reserveCurves
	setAlignment
	setCurve
	setGlyphScale
	setHighlight
	setLineSpacing
	setRect
	setReveal
	setSnapToViewportScale
	setSpeed
	setString
	setStyle
	setWordBreak
	setYFlip
	spool
	affirmStyle
	setFont
	setTextSize

Function List

Detailed Description

Function Documentation