TextField Class Extensions

Scaleform introduces many extensions to the TextField class, making it more flexible and functional than the built-in TextField class in Flash 8. Some of the provided extensions replicate the same or similar behavior as TextField in Flash 9. Additional extensions provide functionality for better control of IME, alignment, text size and appearance, text filter effects (e.g., shadow, blur), embedded images, selection and clipboard operations.

This section describes general purpose extension properties and methods.

autoFit property

autoFit:Boolean [read-write]

Scaleform version: 2.0.39

Sets on/off font auto-hinting. The default value is false.

appendText () method

public function appendText(newText:String):void

Scaleform version: 2.0.37

Appends the string specified by the newText parameter to the end of the text of the text field. This method is significantly more efficient than an addition assignment (+=) on a text property (e.g., my_txt.text += appendingText), especially for a text field that contains a large amount of text.

Note: This method will not work if a style sheet is applied to the text field.

Parameters
newText:String - The string to append to the existing text.

See also:

appendHtml()

appendHtml () method

public function appendHtml(newHtml:String):void

Scaleform version: 2.0.37

Appends the HTML specified by the newHtml parameter to the end of the text of the text field. This method is more efficient than an addition assignment (+=) on an htmlText property (such as txt.htmlText += moreHtml). The regular += on an htmlText property generates the HTML string, appends the new HTML portion and then parses the entire HTML from scratch. This function does incremental HTML parsing, i.e., it parses only the HTML from the newHtml string parameter (that is why the HTML in the newHtml parameter should be well-formed, which is not necessary for the += operator). It is particularly important for a text field that contains a large amount of content.

Note: This method will not work if a style sheet is applied to the text field.

Parameters

newHtml:String - The string with HTML to append to the existing text.

See also: appendText()

caretIndex property

caretIndex:Number [read-only]

Scaleform version: 2.0.37

This property represents the index of the insertion point (caret or cursor) position. If the text field is not focused and caret position is not displayed (by a blinking cursor) it represents the last caret position before the text field loses the focus; or 0, if the text field has not had focus. This property contains the same value as the method Selection.getCaretIndex() returns; however, the caretIndex is accessible even if the text field is not focused, whereas the Selection.getCaretIndex() returns -1 in this case. The caret index is zero-based (so, the first position is 0).

See also:

Selection.getCaretIndex()

getCharBoundaries () method

public function getCharBoundaries(charIndex:Number): flash.geom.Rectangle

Scaleform version: 2.0.37

This method returns a rectangle that is the bounding box of the character. Note, this method returns the rectangle, calculated with using advance values of each glyph. This means that the returned rectangle wouldn’t be the exact one (see the picture; the red rectangles demonstrate boundaries for the ‘a’, ‘w’ and ‘k’):

Parameters
charIndex:Number - The zero-based index value for the character (for example, the first position is 0, the second position is 1, and so on)

Returns
flash.geom.Rectangle - A rectangle with x and y minimum and maximum values defining the bounding box of the character. Coordinates are in the text field’s coordinate space, i.e., the (0,0) point corresponds to the text field’s top left corner.

See also: getExactCharBoundaries()

getExactCharBoundaries () method

public function getExactCharBoundaries(charIndex:Number): flash.geom.Rectangle

Scaleform version: 2.0.37

This method returns a rectangle that is the exact bounding box of the character. Note: This method returns the rectangle, calculated with using real width of each glyph (in contrary to getCharBoundaries() that uses advance values). The height of the rectangle is the height of the entire line. See the picture: the red rectangles demonstrate exact boundaries for the ‘a’, ‘w’ and ‘k’:

Parameters
charIndex:Number - The zero-based index value for the character (e.g., the first position is 0, the second position is 1)

Returns
flash.geom.Rectangle - A rectangle with x and y minimum and maximum values defining the exact bounding box of the character. Coordinates are in the text field’s coordinate space, i.e., the (0,0) point corresponds to the text field’s top left corner.

See also: getCharBoundaries()

getCharIndexAtPoint () method

public function getCharIndexAtPoint(x:Number, y:Number): Number

Scaleform version: 2.0.37 This method returns the zero-based index value of the character at the point specified by the x and y parameters.

Parameters
x:Number - The x coordinate of the character.

y:Number - The y coordinate of the character.

Returns
Number - The zero-based index value of the character (e.g., the first position is 0, the second position is 1). Returns -1 if the point is not over any character.

getFirstCharInParagraph () method

public function getFirstCharInParagraph(charIndex:Number): Number

Scaleform version: 2.0.37 This method returns the index of the first character in the paragraph that contains the character at the charIndex index.

Parameters
charIndex:Number - The zero-based index value of the character (e.g., the first character is 0, the second character is 1).

Returns
Number - The zero-based index value of the first character in the same paragraph.

getLineIndexAtPoint () method

public function getLineIndexAtPoint(x:Number, y:Number): Number

Scaleform version: 2.0.37 This method returns the zero-based index value of the line at the point specified by the x and y parameters.

Parameters
x:Number - The x coordinate of the line.

y:Number - The y coordinate of the line.

Returns
Number - The zero-based index value of the line (e.g., the first line is 0, the second line is 1). Returns -1 if the point is not over any line.

getLineLength() method

public function getLineLength(lineIndex:Number): Number

Scaleform version: 2.0.37

This method returns the number of characters in a specific text line.

Parameters
lineIndex:Number - The zero-based index value of the line (e.g., the first line is 0, the second line is 1).

Returns
Number - The number of characters in the line.

getLineMetrics() method

public function getLineMetrics(lineIndex:Number): Object

Scaleform version: 2.0.43

This method returns metrics information about a given text line. The returning object will contain the following members set:

ascent : Number The ascent value of the text is the length from the baseline to the top of the line height in pixels.

descent : Number The descent value of the text is the length from the baseline to the bottom depth of the line in pixels.

height : Number The height value of the text of the selected lines (not necessarily the complete text) in pixels.

leading : Number The leading value is the measurement of the vertical distance between the lines of text.

width : Number The width value is the width of the text of the selected lines (not necessarily the complete text) in pixels.

x : Number The x value is the left position of the first character in pixels.

Parameters
lineIndex:Number - The zero-based index value of the line (e.g., the first line is 0, the second line is 1).

Returns
Number – An object with metrics information.

getLineOffset () method

public function getLineOffset(lineIndex:Number): Number

Scaleform version: 2.0.37

This method returns the character index of the first character in the line that the lineIndex parameter specifies.

Parameters
lineIndex:Number - The zero-based index value of the line (e.g., the first line is 0, the second line is 1).

Returns
Number - The zero-based index value of the first character in the line.

getLineText () method

public function getLineText(lineIndex:Number): String

Scaleform version: 2.0.43

This method returns the text of the line specified by the lineIndex parameter.

Parameters
lineIndex:Number - The zero-based index value of the line (e.g., the first line is 0, the second line is 1).

Returns
String - The text string contained in the specified line.

hitTestDisable property

hitTestDisable:Boolean [read-write]

Scaleform version: 1.2.32

When set to true, the MovieClip.hitTest function will ignore this text field during hit test detection. In addition, all other mouse events are not propagated to the text field.

The default value is false.

noTranslate property

noTranslate:Boolean [read-write]

Scaleform version: 1.2.34

If set to true, prevents GFxTranslator::Translate callback from being called for the text field.

The default value is false.

numLines property

numLines:Number  [read-only]

Scaleform version: 2.0.43

This property represents the number of text lines in a multi-line text field. If the wordWrap property is set to true, the number of lines increases when text wraps.

topmostLevel property

topmostLevel:Boolean [read-write]

Scaleform version: 2.1.50

If the property is set to true then this character will be displayed on the top of all other characters regardless of its depth. This property is useful for implementing custom mouse cursors and popups that need to be drawn above objects from all levels. The default value is false.

In case of marking several characters as "topmostLevel", the draw order is as follows: * Up to Scaleform 3.0.71, the draw order of characters marked as "topmostLevel" depend on the order of setting this property to true (thus, the character first marked as topmost will be drawn first); * Starting from Scaleform 3.0.72, the draw order is the same as it would be without marking the characters topmost, i.e. if objectA was drawn underneath the objectB, then after making them topmost the objectA will still be under objectB, regardless of the order of setting "topmostLevel" property to true. Note: Once a character is marked as "topmostLevel", the swapDepth ActionScript function will not have any effect on this character.

Note: Only transformation properties will be inherited from the character's current parent while this property is set to true. This means that other properties of the parent and ancestor nodes will no longer be applied to the topmostLevel node, including visibility, ColorTransform, filters, etc. If these properties are desired, they should be propagated on a case-by-case basis by querying them from the parent, and applying them to the topmostLevel child in Actionscript.

See also:

MovieClip.topmostLevel
Button.topmostLevel

focusGroupMask property

focusGroupMask : Number

Scaleform version: 3.3.84

This property sets a bitmask to a stage character and ALL of its children. This bitmask assigns focus group ownership to the character, meaning only the controllers denoted in the bitmask are able to move focus into and within the character. Focus groups can be associated with controllers by using setControllerFocusGroup extension method.

For example, let’s assume that “button1” is to be focusable only by controller 0 and “movieclip2” by controllers 0 and 1. To achieve this behavior, associate focus groups with the controllers:

Selection.setControllerFocusGroup(0, 0);
Selection.setControllerFocusGroup(1, 1);

button1.focusGroupMask = 0x1; // bit 0 – focus group 0
movieclip2.focusGroupMask = 0x1 | 0x2 // bits 0 and 1 – focus groups 0 and 1

The “focusGroupMask” bitmask may be set to the parent movieclip. This will propogate the mask value to all of its children.