TextField Class

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock

	Chapter 18. ActionScript Language Reference

TextField Class

Flash 6

display and manipulate text on screen

Constructor

None. TextField objects are created manually in the authoring tool or programmatically via the MovieClip.createTextField( ) method.

Properties

_alpha: Opacity percentage: 0 is transparent; 100 is opaque.
autoSize: Matches the text field's bounding rectangle size to its text.
background: Boolean; turns text field background on and off.
backgroundColor: RGB number specifying the text field's background color.
border: Boolean; turns text field border on and off.
borderColor: RGB number specifying the text field's border color.
bottomScroll: The 1-relative index of the text field's lowest visible line.
condenseWhite: Boolean; enables or disables condensing of whitespace in HTML text.
embedFonts: Boolean; renders text using fonts exported with the movie.
_height: Height of the text field's bounding box, in pixels.
hscroll: Text's horizontal scroll position, in pixels.
html: Boolean; enables or disables HTML display.
htmlText: HTML source code to render in the text field.
length: The number of characters in the text field.
maxChars: Limits the allowed length of user input.
maxhscroll: The farthest position text can be scrolled to the left.
maxscroll: The last legal top line of a text field.
multiline: Boolean; enables or disables multiple-line user input.
_name: The instance name of the TextField object.
_parent: A reference to the movie clip in which the text field resides.
password: Boolean; obscures characters displayed in the field.
restrict: Limits text entry to a series of characters.
_rotation: Rotation, in degrees, of the text field.
scroll: The current top line displayed in the text field.
selectable: Boolean; enables or disables selection by the user.
tabEnabled: Boolean; includes or excludes the text field from the current tab order.
tabIndex: Specifies the text field's index in the custom tab order.
_target: The target path of the text field, in slash syntax.
text: Specifies the characters to be rendered in the field.
textColor: Sets the color for all characters in the text field.
textHeight: Pixel height of all the text in the text field.
textWidth: Pixel width of the longest line in the text field.
type: Specifies whether the field can accept user input.
_url: The network address of the movie clip that contains the field.
variable: Associates a variable with the text property.
_visible: Boolean; whether the text field is shown or hidden.
_width: Width of the text field's bounding box, in pixels.
wordWrap: Boolean; enables or disables automatic line-breaking for long lines.
_x: Horizontal location of the text field, in pixels.
_xmouse: Horizontal location of mouse pointer, relative to the text field.
_xscale: Width of the text field, as a percentage of original.
_y: Vertical location of the text field, in pixels.
_ymouse: Vertical location of mouse pointer, relative to the text field.
_yscale: Height of the text field, as a percentage of original.

Class Methods

getFontList( ): Returns an array of fonts on the user's system.

Methods

addListener( ): Registers an object to receive onChanged( ) and onScroller( ) events.
getDepth( ): Returns the position of the text field in the movie stack.
getNewTextFormat( ): Retrieves the default TextFormat object for the text field.
getTextFormat( ): Retrieves a TextFormat object for specified characters.
removeListener( ): Cancels event notices for the specified listener.
removeTextField( ): Deletes a runtime-created text field.
replaceSel( ): Replaces selected text (without disturbing formatting).
setNewTextFormat( ): Sets the default formatting for the text field.
setTextFormat( ): Sets the formatting of specified characters.

Event Handlers

onChanged( ): Callback invoked when user input is detected.
onKillFocus( ): Callback invoked when the field loses focus.
onScroller( ): Callback invoked when any scroll property changes.
onSetFocus( ): Callback invoked when the field gains focus.

Listener Events

onChanged( ): Occurs when user input is detected.
onScroller( ): Occurs when any scroll property changes.

Description

The TextField class provides control over text displayed on screen. Each TextField object represents a rectangular text container that can be filled with text, sized, or formatted, and can even receive user input. When we speak of a "text field," we mean the rectangular container on screen; when we speak of a TextField object or instance, we mean the ActionScript object that controls a text field.

TextField objects are not constructed with the new operator; instead, they are created automatically by Flash whenever author-time text is drawn (with the Text tool) or when the MovieClip.createTextField( ) method is invoked. For example, the following code creates a text field named theField_txt, and places it on depth 1, at Stage coordinates (0,0), with a width of 200 and a height of 20. The this keyword refers to the current movie clip. The suffix "_txt" activates code hinting in the Actions panel:

this.createTextField("theField_txt", 1, 0, 0, 200, 20);

In order to gain access to a TextField instance for a field created at authoring time, we must set its type to Dynamic Text or Input Text and assign it an instance name via the Property inspector.

The following steps describe the typical workflow for creating an ActionScript-controllable text field at authoring time:

Select the Text tool.
Drag a rectangle big enough to display the desired text on stage .
Make sure the Property inspector (Window Properties) is open.
In the Property inspector, for Type, select Dynamic Text or Input Text (the default type, Static Text, cannot be accessed through ActionScript).
In the Property inspector, for Instance Name, type someName_txt. An Instance Name cannot be specified until the Type is set, as described in Step 4.

For instructions on deleting a text field at runtime, see the TextField.removeTextField( ) method.

Plain text displayed in a text field is retrieved through the text property and set through either the replaceSel( ) method or the text property. HTML text can be set through the htmlText property, provided that the html property is also set.

Prior to Flash 6, a text field's ActionScript identifier (known as its "variable") was synonymous with the content of the field, but in Flash 6, a text field's identifier is an object instance name. The contents of the text field are retrieved and set in Flash 6 via the TextField.text property.

Hence, in Flash 5, we used the following syntax to set the highScore_txt text field to "15, 000":

highScore_txt = "15, 000";

But in Flash 6, we must use the text property to set a text field's text:

highScore_txt.text = "15, 000";

The Var: text box in Flash MX's text field Property inspector is retained for backward compatibility, as is the TextField.variable property. When authoring for Flash Player 6, assign all text fields an instance name and use the text property to access their content.

By default, Dynamic and Input text fields are selectable by the user. To create a nonselectable text field for display only, set its selectable property to false:

output_txt.selectable = false;

When a user selects a portion of a dynamic or user-input text field, the indexes of the selected characters are stored in the Selection object. Using the Selection object, we can check which part of a text field a user has selected; we can even select a part of a text field programmatically. The Selection object can also give keyboard focus to a particular text field or tell us which text field is currently selected by the user. See Selection.onSetFocus( ), TextField.onKillFocus( ), and TextField.onSetFocus( ).

For author-time text fields, many TextField object properties can be set through the Property inspector interface; any options set at authoring time are reflected at runtime by the corresponding TextField instance's properties.

We can respond to changes in a text field's scroll position or content via the TextField events onChanged( ) and onScroller( ).

To format the appearance of text in a text field, we use either a TextFormat object or HTML display. For details, see the following TextField entries: embedFonts, getFontList( ), getTextFormat( ), getNewTextFormat( ), html, htmlText, setFontList( ), setTextFormat( ), setNewTextFormat( ), and textColor( ), and see the TextFormat class entry. The border and background color of a text field's containing rectangle can also be set; see the following TextField entries: border, borderColor, background, and backgroundColor.

Prior to Flash 6, text fields were not formally accessible as objects. As of Flash 6, the TextField class lets us manipulate text fields much as we do movie clips, by setting position, size, rotation, etc. In fact, many text field properties are borrowed directly from the MovieClip class (for example, _x, _y, _width, _height, and _rotation). For the sake of backward compatibility, text field properties corresponding to movie clip properties that existed prior to Flash 6 are prefixed with an underscore (_). To conform more closely with other ECMA-262 languages, properties that are completely new in Flash 6 do not use the underscore convention.

Bugs

In Flash 6, built-in properties set on TextField.prototype are not inherited by text field instances, so custom default values cannot be assigned for all text fields in a movie:

// This attempt to give all text fields a border by default fails in Flash 6 TextField.prototype.border = true;