Table of Contents

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:

  1. Select the Text tool.

  2. Drag a rectangle big enough to display the desired text on stage .

  3. Make sure the Property inspector (Window figs/U2192.gif Properties) is open.

  4. In the Property inspector, for Type, select Dynamic Text or Input Text (the default type, Static Text, cannot be accessed through ActionScript).

  5. 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;

See Also

MovieClip.createTextField( ), the TextFormat class; Chapter 17


Table of Contents