Top Level

Class TextField

Object


public dynamic class TextField
extends Object

Player version: Flash Player 6

The TextField class is used to create areas for text display and input. All dynamic and input text fields in a SWF file are instances of the TextField class. You can use the TextField class to perform low-level text rendering. However, in Flex, you typically use the Label, Text, TextArea, and TextInput controls to process text. You can give a text field an instance name in the Property inspector and use the methods and properties of the TextField class to manipulate it with ActionScript. TextField instance names are displayed in the Movie Explorer and in the Insert Target Path dialog box in the Actions panel.

To create a text field dynamically, you do not use the new operator. Instead, you use MovieClip.createTextField().

The methods of the TextField class let you set, select, and manipulate text in a dynamic or input text field that you create during authoring or at runtime.

ActionScript provides several ways to format your text at runtime. The TextFormat class lets you set character and paragraph formatting for TextField objects. In Flash Player 7 and later, you can apply Cascading Style Sheets (CSS) styles to text fields using the TextField.styleSheet property and the StyleSheet class. You can use CSS to style built-in HTML tags, define new formatting tags, or apply styles. You can assign HTML formatted text, which might optionally use CSS styles, directly to a text field. In Flash Player 7 and later, HTML text that you assign to a text field can contain embedded media (movie clips, SWF files, JPEG files, GIF files, PNG files). The text wraps around the embedded media in the same way that a web browser wraps text around media embedded in an HTML document.

Flash Player supports a subset of HTML tags that you can use to format text.

See also
Object class, MovieClip.createTextField()



Property Summary
_alpha : Number
Sets or retrieves the alpha transparency value of the text field.
antiAliasType : String
The type of anti-aliasing used for this TextField instance.
autoSize : Object
Controls automatic sizing and alignment of text fields.
background : Boolean
Specifies if the text field has a background fill.
backgroundColor : Number
The color of the text field background.
border : Boolean
Specifies if the text field has a border.
borderColor : Number
The color of the text field border.
bottomScroll : Number  [read-only]
An integer (one-based index) that indicates the bottommost line that is currently visible the text field.
condenseWhite : Boolean
A Boolean value that specifies whether extra white space (spaces, line breaks, and so on) in an HTML text field should be removed when the field is rendered in a browser.
embedFonts : Boolean
Specifies whether to render using embedded font outlines.
filters : Array
An indexed array containing each filter object currently associated with the text field.
gridFitType : String
The type of grid fitting used for this TextField instance.
_height : Number
The height of the text field in pixels.
_highquality : Number
Deprecated since Flash Player 7 — This property was deprecated in favor of TextField._quality.
hscroll : Number
Indicates the current horizontal scrolling position.
html : Boolean
A flag that indicates whether the text field contains an HTML representation.
htmlText : String
If the text field is an HTML text field, this property contains the HTML representation of the text field's contents.
length : Number  [read-only]
Indicates the number of characters in a text field.
maxChars : Number
Indicates the maximum number of characters that the text field can contain.
maxhscroll : Number  [read-only]
Indicates the maximum value of TextField.hscroll.
maxscroll : Number  [read-only]
Indicates the maximum value of TextField.scroll.
menu : ContextMenu
Associates the ContextMenu object contextMenu with the text field my_txt.
mouseWheelEnabled : Boolean
A Boolean value that indicates whether Flash Player should automatically scroll multiline text fields when the mouse pointer clicks a text field and the user rolls the mouse wheel.
multiline : Boolean
Indicates whether the text field is a multiline text field.
_name : String
The instance name of the text field.
_parent : MovieClip
A reference to the movie clip or object that contains the current text field or object.
password : Boolean
Specifies whether the text field is a password text field.
_quality : String
The rendering quality used for a SWF file.
restrict : String
Indicates the set of characters that a user may enter into the text field.
_rotation : Number
The rotation of the text field, in degrees, from its original orientation.
scroll : Number
The vertical position of text in a text field.
selectable : Boolean
A Boolean value that indicates whether the text field is selectable.
sharpness : Number
The sharpness of the glyph edges in this TextField instance.
_soundbuftime : Number
The number of seconds a sound prebuffers before it starts to stream.
styleSheet : StyleSheet
Attaches a style sheet to the text field.
tabEnabled : Boolean
Specifies whether the text field is included in automatic tab ordering.
tabIndex : Number
Lets you customize the tab ordering of objects in a SWF file.
_target : String  [read-only]
The target path of the text field instance.
text : String
Indicates the current text in the text field.
textColor : Number
Indicates the color of the text in a text field.
textHeight : Number
Indicates the height of the text.
textWidth : Number
Indicates the width of the text.
thickness : Number
The thickness of the glyph edges in this TextField instance.
type : String
Specifies the type of text field.
_url : String  [read-only]
Retrieves the URL of the SWF file that created the text field.
variable : String
The name of the variable that the text field is associated with.
_visible : Boolean
A Boolean value that indicates whether the text field my_txt is visible.
_width : Number
The width of the text field, in pixels.
wordWrap : Boolean
A Boolean value that indicates if the text field has word wrap.
_x : Number
An integer that sets the x coordinate of a text field relative to the local coordinates of the parent movie clip.
_xmouse : Number  [read-only]
Returns the x coordinate of the mouse position relative to the text field.
_xscale : Number
Determines the horizontal scale of the text field as applied from the registration point of the text field, expressed as a percentage.
_y : Number
The y coordinate of a text field relative to the local coordinates of the parent movie clip.
_ymouse : Number  [read-only]
Indicates the y coordinate of the mouse position relative to the text field.
_yscale : Number
The vertical scale of the text field as applied from the registration point of the text field, expressed as a percentage.

Properties inherited from class Object
__proto__, __resolve, constructor, prototype


Event Summary
onChanged = function(changedField:TextField) {}
Event handler/listener; invoked when the content of a text field changes.
onKillFocus = function(newFocus:Object) {}
Invoked when a text field loses keyboard focus.
onScroller = function(scrolledField:TextField) {}
Event handler/listener; invoked when one of the text field scroll properties changes.
onSetFocus = function(oldFocus:Object) {}
Invoked when a text field receives keyboard focus.


Method Summary
addListener(listener:Object) : Boolean
Registers an object to receive TextField event notifications.
getDepth() : Number
Returns the depth of a text field.
static getFontList() : Array
Returns the names of fonts on the player's host system as an array.
getNewTextFormat() : TextFormat
Returns a TextFormat object containing a copy of the text field's text format object.
getTextFormat([beginIndex:Number], [endIndex:Number]) : TextFormat
Returns a TextFormat object for a character, a range of characters, or an entire TextField object.
removeListener(listener:Object) : Boolean
Removes a listener object previously registered to a text field instance with TextField.addListener().
removeTextField() : Void
Removes the text field.
replaceSel(newText:String) : Void
Replaces the current selection with the contents of the newText parameter.
replaceText(beginIndex:Number, endIndex:Number, newText:String) : Void
Replaces a range of characters, specified by the beginIndex and endIndex parameters, in the specified text field with the contents of the newText parameter.
setNewTextFormat(tf:TextFormat) : Void
Sets the default new text format of a text field.
setTextFormat([beginIndex:Number], [endIndex:Number], textFormat:TextFormat) : Void
Applies the text formatting specified by the textFormat parameter to some or all of the text in a text field.

Methods inherited from class Object
addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch


Property Detail

_alpha Property

public _alpha : Number

Player version: Flash Player 6

Sets or retrieves the alpha transparency value of the text field. Valid values are 0 (fully transparent) to 100 (fully opaque). The default value is 100. Transparency values are not supported for text fields that use device fonts. You must use embedded fonts to use the _alpha transparency property with a text field.

Example
The following code sets the _alpha property of a text field named my_txt to 20%. Create a new font symbol in the library by selecting New Font from the Library options menu. Then set the linkage of the font to my font. Set the linkage for a font symbol to my font. Add the following ActionScript code to your FLA or AS file.
var my_fmt:TextFormat = new TextFormat();
my_fmt.font = "my font";
// where 'my font' is the linkage name of a font in the Library
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 100, 22);
my_txt.border = true;
my_txt.embedFonts = true;
my_txt.text = "Hello World";
my_txt.setTextFormat(my_fmt);
my_txt._alpha = 20;

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
Button._alpha, MovieClip._alpha

antiAliasType Property

public antiAliasType : String

Player version: Flash Player 8

The type of anti-aliasing used for this TextField instance. Advanced anti-aliasing is available only in Flash Player 8 and later. You can control this setting only if the font is embedded (with the embedFonts property set to true). For Flash Player 8, the default setting is "advanced".

To set values for this property, use the following string values:

String value Description
"normal" Applies the regular text anti-aliasing. This matches the type of anti-aliasing that Flash Player used in version 7 and earlier.
"advanced" Applies advanced anti-aliasing, which makes text more legible. (This feature is available as of Flash Player 8.) Advanced anti-aliasing allows for high-quality rendering of font faces at small sizes. It is best used with applications that have a lot of small text. Advanced anti-aliasing is not recommended for fonts that are larger than 48 points.

Example
This example creates two text fields and applies advanced anti-aliasing to the first one only. It assumes that you have a font embedded in the Library with the linkage identifier set to "Times-12". To embed the font, follow these steps:
  1. Open your Library
  2. Click the Library options menu in the upper right corner of the Library
  3. Select "New Font" from the dropdown list
  4. Name the font "Times-12"
  5. Select "Times New Roman" from the font dropdown list
  6. Press the "OK" button
  7. Right-click on the newly created font and select "Linkage..."
  8. Check the "Export for ActionScript" box
  9. Accept the default identifier "Times-12" by pressing the "OK" button
var my_format:TextFormat = new TextFormat();
my_format.font = "Times-12";

var my_text1:TextField = this.createTextField("my_text1", this.getNextHighestDepth(), 10, 10, 300, 30);
my_text1.text = "This text uses advanced anti-aliasing.";
my_text1.antiAliasType = "advanced";
my_text1.border = true;
my_text1.embedFonts = true;
my_text1.setTextFormat(my_format); 

var my_text2:TextField = this.createTextField("my_text2", this.getNextHighestDepth(), 10, 50, 300, 30);
my_text2.text = "This text uses normal anti-aliasing."
my_text2.antiAliasType = "normal";
my_text2.border = true;
my_text2.embedFonts = true;
my_text2.setTextFormat(my_format);

If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

See also
flash.text.TextRenderer, TextField.gridFitType, TextField.thickness, TextField.sharpness

autoSize Property

public autoSize : Object

Player version: Flash Player 6

Controls automatic sizing and alignment of text fields. Acceptable values for autoSize are "none" (the default), "left", "right", and "center". When you set the autoSize property, true is a synonym for "left" and false is a synonym for "none".

The values of autoSize and TextField.wordWrap determine whether a text field expands or contracts to the left side, right side, or bottom side. The default value for each of these properties is false.

If autoSize is set to "none" (the default) or false, then no resizing will occur.

If autoSize is set to "left" or true, then the text is treated as left-justified text, meaning the left side of the text field will remain fixed and any resizing of a single line text field will be on the right side. If the text includes a line break (for example, "\n" or "\r"), then the bottom side will also be resized to fit the next line of text. If wordWrap is also set to true, then only the bottom side of the text field will be resized and the right side will remain fixed.

If autoSize is set to "right", then the text is treated as right-justified text, meaning the right side of the text field will remain fixed and any resizing of a single line text field will be on the left side. If the text includes a line break (for example, "\n" or "\r"), then the bottom side will also be resized to fit the next line of text. If wordWrap is also set to true, then only the bottom side of the text field will be resized and the left side will remain fixed.

If autoSize is set to "center", then the text is treated as center-justified text, meaning any resizing of a single line text field will be equally distributed to both the right and left sides. If the text includes a line break (for example, "\n" or "\r"), then the bottom side will also be resized to fit the next line of text. If wordWrap is also set to true, then only the bottom side of the text field will be resized and the left and right sides will remain fixed.

Example
You can use the following code and enter different values for autoSize to see how the field resizes when these values change. A mouse click while the SWF file is playing will replace each text field's "short text" string with longer text using several different settings for autoSize.
this.createTextField("left_txt", 997, 10, 10, 70, 30);
this.createTextField("center_txt", 998, 10, 50, 70, 30);
this.createTextField("right_txt", 999, 10, 100, 70, 30);
this.createTextField("true_txt", 1000, 10, 150, 70, 30);
this.createTextField("false_txt", 1001, 10, 200, 70, 30);

left_txt.text = "short text";
left_txt.border = true;

center_txt.text = "short text";
center_txt.border = true;

right_txt.text = "short text";
right_txt.border = true;

true_txt.text = "short text";
true_txt.border = true;

false_txt.text = "short text";
false_txt.border = true;

// create a mouse listener object to detect mouse clicks
var myMouseListener:Object = new Object();
// define a function that executes when a user clicks the mouse
myMouseListener.onMouseDown = function() {
    left_txt.autoSize = "left";
    left_txt.text = "This is much longer text";
    center_txt.autoSize = "center";
    center_txt.text = "This is much longer text";
    right_txt.autoSize = "right";
    right_txt.text = "This is much longer text";
    true_txt.autoSize = true;
    true_txt.text = "This is much longer text";  
    false_txt.autoSize = false;
    false_txt.text = "This is much longer text";
};
// register the listener object with the Mouse object
Mouse.addListener(myMouseListener);


background Property

public background : Boolean

Player version: Flash Player 6

Specifies if the text field has a background fill. If true, the text field has a background fill. If false, the text field has no background fill.

Example
The following example creates a text field with a background color that toggles on and off when nearly any key on the keyboard is pressed.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 320, 240);
my_txt.border = true;
my_txt.text = "Lorum ipsum";
my_txt.backgroundColor = 0xFF0000;

var keyListener:Object = new Object();
keyListener.onKeyDown = function() {
    my_txt.background = !my_txt.background;
};
Key.addListener(keyListener);

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


backgroundColor Property

public backgroundColor : Number

Player version: Flash Player 6

The color of the text field background. Default is 0xFFFFFF (white). This property may be retrieved or set, even if there currently is no background, but the color is only visible if the text field has a border.

Example
See the example for TextField.background.

See also
TextField.background

border Property

public border : Boolean

Player version: Flash Player 6

Specifies if the text field has a border. If true, the text field has a border. If false, the text field has no border.

Example
The following example creates a text field called my_txt, sets the border property to true, and displays some text in the field.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 320, 240);
my_txt.border = true;
my_txt.text = "Lorum ipsum";

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


borderColor Property

public borderColor : Number

Player version: Flash Player 6

The color of the text field border. The default is 0x000000 (black). This property may be retrieved or set, even if there is currently no border.

Example
The following example creates a text field called my_txt, sets the border property to true, and displays some text in the field.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 320, 240);
my_txt.border = true;
my_txt.borderColor = 0x00FF00;
my_txt.text = "Lorum ipsum";

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField.border

bottomScroll Property

public bottomScroll : Number  [read-only]

Player version: Flash Player 6

An integer (one-based index) that indicates the bottommost line that is currently visible the text field. Think of the text field as a window onto a block of text. The property TextField.scroll is the one-based index of the topmost visible line in the window.

All the text between lines TextField.scroll and TextField.bottomScroll is currently visible in the text field.

Example
The following example creates a text field and fills it with text. You must insert a button (with the instance name "my_btn"), and when you click it, the scroll and bottomScroll properties for the text field are then traced for the comment_txt field.
this.createTextField("comment_txt", this.getNextHighestDepth(), 0, 0, 160, 120);
comment_txt.html = true;
comment_txt.selectable = true;
comment_txt.multiline = true;
comment_txt.wordWrap = true;
comment_txt.htmlText = "<b>What is hexadecimal?</b><br>"
    + "The hexadecimal color system uses six digits to represent color values. "
    + "Each digit has sixteen possible values or characters. The characters range"
    + " from 0 to 9 and then A to F. Black is represented by (#000000) and white, "
    + "at the opposite end of the color system, is (#FFFFFF).";
my_btn.onRelease = function() {
    trace("scroll: "+comment_txt.scroll);
    trace("bottomScroll: "+comment_txt.bottomScroll);
};

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


condenseWhite Property

public condenseWhite : Boolean

Player version: Flash Player 6

A Boolean value that specifies whether extra white space (spaces, line breaks, and so on) in an HTML text field should be removed when the field is rendered in a browser. The default value is false.

If you set this value to true, you must use standard HTML commands such as <BR> and <P> to place line breaks in the text field.

If the text field's .html is false, this property is ignored.

Example
The following example creates two text fields, called first_txt and second_txt. The white space is removed from the second text field. Add the following ActionScript to your FLA or AS file:
var my_str:String = "Hello\tWorld\nHow are you?\t\t\tEnd";

this.createTextField("first_txt", this.getNextHighestDepth(), 10, 10, 160, 120);
first_txt.html = true;
first_txt.multiline = true;
first_txt.wordWrap = true;
first_txt.condenseWhite = false;
first_txt.border = true;
first_txt.htmlText = my_str;

this.createTextField("second_txt", this.getNextHighestDepth(), 180, 10, 160, 120);
second_txt.html = true;
second_txt.multiline = true;
second_txt.wordWrap = true;
second_txt.condenseWhite = true;
second_txt.border = true;
second_txt.htmlText = my_str;

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField.html

embedFonts Property

public embedFonts : Boolean

Player version: Flash Player 6

Specifies whether to render using embedded font outlines. A Boolean value that, when true, renders the text field using embedded font outlines. If false, it renders the text field using device fonts.

If you set embedFonts to true for a text field, then you must specify a font for that text via the font property of a TextFormat object applied to the text field. If the specified font does not exist in the library (with the corresponding Linkage Instance name), then the text will not be displayed.

Example
In this example, you need to create a dynamic text field called my_txt, and then use the following ActionScript to embed fonts and rotate the text field. The reference to my font refers to a Font symbol in the library, with linkage set to my font. The example assumes that you have a Font symbol in the library called my font, with linkage properties set as follows: the identifier set to my font and Export for ActionScript and Export in First Frame selected.
var my_fmt:TextFormat = new TextFormat();
my_fmt.font = "my font";

this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 160, 120);
my_txt.wordWrap = true;
my_txt.embedFonts = true;
my_txt.text = "Hello world";
my_txt.setTextFormat(my_fmt);
my_txt._rotation = 45;

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


filters Property

public filters : Array

Player version: Flash Player 8

An indexed array containing each filter object currently associated with the text field. The flash.filters package contains several classes that define specific filters that you can use.

Filters can be applied in the Flash authoring tool at design-time, or at runtime using ActionScript code. To apply a filter using ActionScript, you must make a temporary copy of the entire TextField.filters array, modify the temporary array, and then assign the value of the temporary array back to the TextField.filters array. You cannot directly add a new filter object to the TextField.filters array. The following code has no effect on the target text field, named myTextField:

myTextField.filters[0].push(myDropShadow);

To add a filter using ActionScript, you must follow these steps (assume that the target movie clip is named myTextField):

  1. Create a new filter object using the constructor function of your chosen filter class.
  2. Assign the value of the myTextField.filters array to a temporary array, such as one named myFilters.
  3. Add the new filter object to the temporary array, myFilters.
  4. Assign the value of the temporary array to the myTextField.filters array.

If the filters array is empty, you need not use a temporary array. Instead, you can directly assign an array literal that contains one or more filter objects that you have created.

To modify an existing filter object, whether it was created at design-time or at runtime, you must use the technique of modifying a copy of the filters array, as follows:

  1. Assign the value of the myTextField.filters array to a temporary array, such as one named myFilters.
  2. Modify the property using the temporary array, myFilters. For example, if you want to set the quality property of the first filter in the array, you could use the following code: myList[0].quality = 1;
  3. Assign the value of the temporary array to the myTextField.filters array.

To clear the filters for a text field, set filters to an empty array ([]).

If you are working with a filters array that contains multiple filters and you need to track the type of filter assigned to each array index, you can maintain your own filters array and use a separate data structure to track the type of filter associated with each array index. There is no simple way to determine the type of filter associated with each filters array index.

Example
The following example adds a drop shadow filter to a text field named myTextField.
var myDropFilter = new flash.filters.DropShadowFilter();
var myFilters:Array = myTextField.filters;
myFilters.push(myDropFilter);
myTextField.filters = myFilters;

The following example changes the quality setting of the first filter in the array to 15 (this example works only if at least one filter object has been associated with the myTextField text field).

var myList:Array = myTextField.filters;
myList[0].quality = 15;
myTextField.filters = myList;

See also
flash.filters package

gridFitType Property

public gridFitType : String

Player version: Flash Player 8

The type of grid fitting used for this TextField instance. This property applies only if the antiAliasType property of the text field is set to "advanced".

For the gridFitType property, you can use the following string values:

String value Description
"none" Specifies no grid fitting. Horizontal and vertical lines in the glyphs are not forced to the pixel grid. This setting is usually good for animation or for large font sizes.
"pixel" Specifies that strong horizontal and vertical lines are fit to the pixel grid. This setting works only for left-aligned text fields. To use this setting, the antiAliasType property of the text field must be set to "advanced". This setting generally provides the best legibility for left-aligned text.
"subpixel" Specifies that strong horizontal and vertical lines are fit to the subpixel grid on an LCD monitor. To use this setting, the antiAliasType property of the text field must be set to "advanced". The "subpixel" setting is often good for right-aligned or centered dynamic text, and it is sometimes a useful trade-off for animation versus text quality.

Example
This example shows three text fields that use the different gridFitType settings. It assumes that you have a font embedded in the Library with the linkage identifier set to "Times-12". To embed the font, follow these steps:
  1. Open your Library
  2. Click the Library options menu in the upper right corner of the Library
  3. Select "New Font" from the dropdown list
  4. Name the font "Times-12"
  5. Select "Times New Roman" from the font dropdown list
  6. Press the "OK" button
  7. Right-click on the newly created font and select "Linkage..."
  8. Check the "Export for ActionScript" box
  9. Accept the default identifier "Times-12" by pressing the "OK" button
var my_format:TextFormat = new TextFormat();
my_format.font = "Times-12";

var my_text1:TextField = this.createTextField("my_text1", this.getNextHighestDepth(), 9.5, 10, 400, 100);
my_text1.text = "this.gridFitType = none";
my_text1.embedFonts = true;
my_text1.antiAliasType = "advanced";
my_text1.gridFitType = "none";
my_text1.setTextFormat(my_format); 

var my_text2:TextField = this.createTextField("my_text2", this.getNextHighestDepth(), 9.5, 40, 400, 100);
my_text2.text = "this.gridFitType = advanced";
my_text2.embedFonts = true;
my_text2.antiAliasType = "advanced";
my_text2.gridFitType = "pixel";
my_text2.setTextFormat(my_format); 

var my_text3:TextField = this.createTextField("my_text3", this.getNextHighestDepth(), 9.5, 70, 400, 100);
my_text3.text = "this.gridFitType = subpixel";
my_text3.embedFonts = true;
my_text3.antiAliasType = "advanced";
my_text3.gridFitType = "subpixel";
my_text3.setTextFormat(my_format);

If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

See also
flash.text.TextRenderer, TextField.antiAliasType, TextField.sharpness

_height Property

public _height : Number

Player version: Flash Player 6

The height of the text field in pixels.

Example
The following code example sets the height and width of a text field:
my_txt._width = 200;
my_txt._height = 200;


_highquality Property

public _highquality : Number

Deprecated since Flash Player 7 — This property was deprecated in favor of TextField._quality.

Player version: Flash Player 6

Specifies the level of anti-aliasing applied to the current SWF file. Specify 2 (best quality) to apply high quality with bitmap smoothing always on. Specify 1 (high quality) to apply anti-aliasing; this smoothes bitmaps if the SWF file does not contain animation and is the default value. Specify 0 (low quality) to prevent anti-aliasing.

See also
TextField._quality

hscroll Property

public hscroll : Number

Player version: Flash Player 6

Indicates the current horizontal scrolling position. If the hscroll property is 0, the text is not horizontally scrolled.

The units of horizontal scrolling are pixels, while the units of vertical scrolling are lines. Horizontal scrolling is measured in pixels because most fonts you typically use are proportionally spaced; meaning, the characters can have different widths. Flash performs vertical scrolling by line because users usually want to see a line of text in its entirety, as opposed to seeing a partial line. Even if there are multiple fonts on a line, the height of the line adjusts to fit the largest font in use.

Note: The hscroll property is zero-based—not one-based like the vertical scrolling property TextField.scroll.

Example
The following example scrolls the my_txt text field horizontally using two buttons called scrollLeft_btn and scrollRight_btn. The amount of scroll displays in a text field called scroll_txt. Add the following ActionScript to your FLA or AS file:
this.createTextField("scroll_txt", this.getNextHighestDepth(), 10, 10, 160, 20);
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 30, 160, 22);
my_txt.border = true;
my_txt.multiline = false;
my_txt.wordWrap = false;
my_txt.text = "Lorem ipsum dolor sit amet, consectetuer adipiscing...";

scrollLeft_btn.onRelease = function() {
    my_txt.hscroll -= 10;
    scroll_txt.text = my_txt.hscroll+" of "+my_txt.maxhscroll;
};
scrollRight_btn.onRelease = function() {
    my_txt.hscroll += 10;
    scroll_txt.text = my_txt.hscroll+" of "+my_txt.maxhscroll;
};

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField.maxhscroll, TextField.scroll

html Property

public html : Boolean

Player version: Flash Player 6

A flag that indicates whether the text field contains an HTML representation. If the html property is true, the text field is an HTML text field. If html is false, the text field is a non-HTML text field.

Example
The following example creates a text field that sets the html property to true. HTML-formatted text displays in the text field.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 160, 22);
my_txt.html = true;
my_txt.htmlText = "<b> this is bold text </b>";

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField.htmlText

htmlText Property

public htmlText : String

Player version: Flash Player 6

If the text field is an HTML text field, this property contains the HTML representation of the text field's contents. If the text field is not an HTML text field, it behaves identically to the text property. You can indicate that a text field is an HTML text field in the Property inspector, or by setting the text field's html property to true.

Example
The following example creates a text field that sets the html property to true. HTML-formatted text displays in the text field.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 160, 22);
my_txt.html = true;
my_txt.htmlText = "<b> this is bold text </b>";

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField.html, asfunction

length Property

public length : Number  [read-only]

Player version: Flash Player 6

Indicates the number of characters in a text field. This property returns the same value as text.length, but is faster. A character such as tab (\t) counts as one character.

Example
The following example outputs the number of characters in the date_txt text field, which displays the current date.
var today:Date = new Date();
this.createTextField("date_txt", this.getNextHighestDepth(), 10, 10, 100, 22);
date_txt.autoSize = true;
date_txt.text = today.toString();
trace(date_txt.length);

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


maxChars Property

public maxChars : Number

Player version: Flash Player 6

Indicates the maximum number of characters that the text field can contain. A script may insert more text than maxChars allows; the maxChars property indicates only how much text a user can enter. If the value of this property is null, there is no limit on the amount of text a user can enter.

Example
The following example creates a text field called age_txt that only lets users enter up to two numbers in the field.
this.createTextField("age_txt", this.getNextHighestDepth(), 10, 10, 30, 22);
age_txt.type = "input";
age_txt.border = true;
age_txt.maxChars = 2;
age_txt.restrict = "0-9";

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


maxhscroll Property

public maxhscroll : Number  [read-only]

Player version: Flash Player 6

Indicates the maximum value of TextField.hscroll.

Example
See the example for TextField.hscroll.


maxscroll Property

public maxscroll : Number  [read-only]

Player version: Flash Player 6

Indicates the maximum value of TextField.scroll.

Example
The following example sets the maximum value for the scrolling text field my_txt. Create two buttons, scrollUp_btn and scrollDown_btn, to scroll the text field. Add the following ActionScript to your FLA or AS file.
this.createTextField("scroll_txt", this.getNextHighestDepth(), 10, 10, 160, 20);
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 30, 320, 240);
my_txt.multiline = true;
my_txt.wordWrap = true;
for (var i = 0; i<10; i++) {
    my_txt.text += "Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh "
            + "euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.";
}
scrollUp_btn.onRelease = function() {
    my_txt.scroll--;
    scroll_txt.text = my_txt.scroll+" of "+my_txt.maxscroll;
};
scrollDown_btn.onRelease = function() {
    my_txt.scroll++;
    scroll_txt.text = my_txt.scroll+" of "+my_txt.maxscroll;
};

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


menu Property

public menu : ContextMenu

Player version: Flash Player 7

Associates the ContextMenu object contextMenu with the text field my_txt. The ContextMenu class lets you modify the context menu that appears when the user right-clicks (Windows) or Control-clicks (Macintosh) in Flash Player.

This property works only with selectable (editable) text fields; it has no effect on nonselectable text fields.

In Flex, only top-level components in the application can have context menus. For example, if a DataGrid control is a child of a TabNavigator or VBox container, the DataGrid control cannot have its own context menu.

Example
The following example assigns the ContextMenu object menu_cm to the text field news_txt. The ContextMenu object contains a custom menu item labeled "Resize" with an associated callback handler named doResize(), which could be used to add resizing functionality (not shown):
this.createTextField("news_txt", this.getNextHighestDepth(), 10, 10, 320, 240);
news_txt.border = true;
news_txt.wordWrap = true;
news_txt.multiline = true;
news_txt.text = "To see the custom context menu item, right click (PC) or ";
news_txt.text += "control click (Mac) within the text field.";
var menu_cm:ContextMenu = new ContextMenu();
menu_cm.customItems.push(new ContextMenuItem("Resize", doResize));

function doResize(obj:TextField, item:ContextMenuItem):Void {
    // "Resize" code here
    trace("you selected: "+item.caption);
}
news_txt.menu = menu_cm;

When you right-click or Control-click within the area of the text field, you see the custom menu item.

Note: You cannot use a menu item that is already used by Flash. For example, Print... (with three dots) is reserved by Flash, so you cannot use this menu item; however, you could use Print.. (with two dots) or any menu item not already used by Flash.

If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

See also
Button class, ContextMenu class, ContextMenuItem class, MovieClip class

mouseWheelEnabled Property

public mouseWheelEnabled : Boolean

Player version: Flash Player 7

A Boolean value that indicates whether Flash Player should automatically scroll multiline text fields when the mouse pointer clicks a text field and the user rolls the mouse wheel. By default, this value is true. This property is useful if you want to prevent mouse wheel scrolling of text fields, or implement your own text field scrolling.

Example
The following example creates two text fields. The scrollable_txt field has the mouseWheelEnabled property set to true, so scrollable_txt scrolls when you click the field and roll the mouse wheel. The nonscrollable_txt field does not scroll if you click the field and roll the mouse wheel.
var font_array:Array = TextField.getFontList().sort();

this.createTextField("scrollable_txt", this.getNextHighestDepth(), 10, 10, 240, 320);
scrollable_txt.border = true;
scrollable_txt.wordWrap = true;
scrollable_txt.multiline = true;
scrollable_txt.text = font_array.join("\n");

this.createTextField("nonscrollable_txt", this.getNextHighestDepth(), 260, 10, 240, 320);
nonscrollable_txt.border = true;
nonscrollable_txt.wordWrap = true;
nonscrollable_txt.multiline = true;
nonscrollable_txt.mouseWheelEnabled = false;
nonscrollable_txt.text = font_array.join("\n");

Mouse.onMouseWheel

If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

See also
TextField.mouseWheelEnabled

multiline Property

public multiline : Boolean

Player version: Flash Player 6

Indicates whether the text field is a multiline text field. If the value is true, the text field is multiline; if the value is false, the text field is a single-line text field.

Example
The following example creates a multiline text field called fontList_txt that displays a long, multiline list of fonts.
var font_array:Array = TextField.getFontList().sort();

this.createTextField("fontList_txt", this.getNextHighestDepth(), 10, 10, 240, 320);
fontList_txt.border = true;
fontList_txt.wordWrap = true;
fontList_txt.multiline = true;
fontList_txt.text = font_array.join("\n");

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


_name Property

public _name : String

Player version: Flash Player 6

The instance name of the text field.

Example
The following example demonstrates text fields residing at different depths. Create a dynamic text field on the Stage. Add the following ActionScript to your FLA or AS file, which dynamically creates two text fields at runtime and displays their depths in the Output panel.
this.createTextField("first_mc", this.getNextHighestDepth(), 10, 10, 100, 22);
this.createTextField("second_mc", this.getNextHighestDepth(), 10, 10, 100, 22);
for (var prop in this) {
    if (this[prop] instanceof TextField) {
    var this_txt:TextField = this[prop];
    trace(this_txt._name+" is a TextField at depth: "+this_txt.getDepth());
    }
}

When you test the document, the instance name and depth is displayed in the Output panel. When you test the document, the instance name and depth writes to the log file.

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


_parent Property

public _parent : MovieClip

Player version: Flash Player 6

A reference to the movie clip or object that contains the current text field or object. The current object is the one containing the ActionScript code that references _parent.

Use _parent to specify a relative path to movie clips or objects that are above the current text field. You can use _parent to climb up multiple levels in the display list as in the following:

_parent._parent._alpha = 20;

Example
The following ActionScript creates two text fields and outputs information about the _parent of each object. The first text field, first_txt, is created on the main Timeline. The second text field, second_txt, is created inside the movie clip called holder_mc.
this.createTextField("first_txt", this.getNextHighestDepth(), 10, 10, 160, 22);
first_txt.border = true;
trace(first_txt._name+"'s _parent is: "+first_txt._parent);

this.createEmptyMovieClip("holder_mc", this.getNextHighestDepth());
holder_mc.createTextField("second_txt", holder_mc.getNextHighestDepth(), 10, 40, 160, 22);
holder_mc.second_txt.border = true;
trace(holder_mc.second_txt._name+"'s _parent is: "+holder_mc.second_txt._parent);

The following information is displayed in the Output panel: The following information writes to the log file:


      first_txt's _parent is: _level0
      second_txt's _parent is: _level0.holder_mc
      

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
Button._parent, MovieClip._parent, _root global property, targetPath() global function

password Property

public password : Boolean

Player version: Flash Player 6

Specifies whether the text field is a password text field. If the value of password is true, the text field is a password text field and hides the input characters using asterisks instead of the actual characters. If false, the text field is not a password text field. When password mode is enabled, the Cut and Copy commands and their corresponding keyboard accelerators will not function. This security mechanism prevents an unscrupulous user from using the shortcuts to discover a password on an unattended computer.

Example
The following example creates two text fields: username_txt and password_txt. Text is entered into both text fields; however, password_txt has the password property set to true. Therefore, the characters display as asterisks instead of as characters in the password_txt field.
this.createTextField("username_txt", this.getNextHighestDepth(), 10, 10, 100, 22);
username_txt.border = true;
username_txt.type = "input";
username_txt.maxChars = 16;
username_txt.text = "hello";
    
this.createTextField("password_txt", this.getNextHighestDepth(), 10, 40, 100, 22);
password_txt.border = true;
password_txt.type = "input";
password_txt.maxChars = 16;
password_txt.password = true;
password_txt.text = "world";

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


_quality Property

public _quality : String

Player version: Flash Player 6

The rendering quality used for a SWF file. Device fonts are always aliased and, therefore, are unaffected by the _quality property.

Note: Although you can specify this property for a TextField object, it is actually a global property, and you can specify its value simply as _quality. For more information, see the _quality global property.

The _quality property can be set to the following values:

Example
The following example sets the rendering quality to LOW:
my_txt._quality = "LOW";

See also
_quality

restrict Property

public restrict : String

Player version: Flash Player 6

Indicates the set of characters that a user may enter into the text field. If the value of the restrict property is null, you can enter any character. If the value of the restrict property is an empty string, you cannot enter any character. If the value of the restrict property is a string of characters, you can enter only characters in the string into the text field. The string is scanned from left to right. A range may be specified using the dash (-). This only restricts user interaction; a script may put any text into the text field. This property does not synchronize with the Embed Font Outlines check boxes in the Property inspector.

If the string begins with ^, all characters are initially accepted and succeeding characters in the string are excluded from the set of accepted characters. If the string does not begin with ^, no characters are initially accepted and succeeding characters in the string are included in the set of accepted characters.

Example
The following example allows only uppercase characters, spaces, and numbers to be entered into a text field:
my_txt.restrict = "A-Z 0-9";

The following example includes all characters, but excludes lowercase letters:

my_txt.restrict = "^a-z"; 

You can use a backslash to enter a ^ or - verbatim. The accepted backslash sequences are \-, \^ or \\. The backslash must be an actual character in the string, so when specified in ActionScript, a double backslash must be used. For example, the following code includes only the dash (-) and caret (^):

my_txt.restrict = "\\-\\^";

The ^ may be used anywhere in the string to toggle between including characters and excluding characters. The following code includes only uppercase letters, but excludes the uppercase letter Q:

my_txt.restrict = "A-Z^Q"; 

You can use the \u escape sequence to construct restrict strings. The following code includes only the characters from ASCII 32 (space) to ASCII 126 (tilde).

my_txt.restrict = "\u0020-\u007E"; 


_rotation Property

public _rotation : Number

Player version: Flash Player 6

The rotation of the text field, in degrees, from its original orientation. Values from 0 to 180 represent clockwise rotation; values from 0 to -180 represent counterclockwise rotation. Values outside this range are added to or subtracted from 360 to obtain a value within the range. For example, the statement my_txt._rotation = 450 is the same as my_txt._rotation = 90.

Rotation values are not supported for text fields that use device fonts. You must use embedded fonts to use _rotation with a text field.

Example
In this example, you need to create a dynamic text field called my_txt, and then use the following ActionScript to embed fonts and rotate the text field. The reference to my font refers to a Font symbol in the library, with linkage set to my font.
var my_fmt:TextFormat = new TextFormat();
my_fmt.font = "my font";

this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 160, 120);
my_txt.wordWrap = true;
my_txt.embedFonts = true;
my_txt.text = "Hello world";
my_txt.setTextFormat(my_fmt);
my_txt._rotation = 45;

Apply additional formatting for the text field using the TextFormat class.

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
Button._rotation, MovieClip._rotation, TextFormat

scroll Property

public scroll : Number

Player version: Flash Player 6

The vertical position of text in a text field. The scroll property is useful for directing users to a specific paragraph in a long passage, or for creating scrolling text fields. This property can be retrieved and modified.

The units of horizontal scrolling are pixels and the units of vertical scrolling are lines. Horizontal scrolling is measured in pixels because most fonts that you typically use are proportionally spaced, meaning that the characters can have different widths. Flash performs vertical scrolling by line because users usually want to see a line of text in its entirety, as opposed to seeing a partial line. Even if there are multiple fonts on a line, the height of the line adjusts to fit the largest font in use.

Example
The following example sets the maximum value for the scrolling text field my_txt. Create two buttons, scrollUp_btn and scrollDown_btn, to scroll through the text field. Add the following ActionScript code to your FLA or AS file.
this.createTextField("scroll_txt", this.getNextHighestDepth(), 10, 10, 160, 20);
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 30, 320, 240);
my_txt.multiline = true;
my_txt.wordWrap = true;
for (var i = 0; i<10; i++) {
    my_txt.text += "Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy "
        + "nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.";
}
scrollUp_btn.onRelease = function() {
    my_txt.scroll--;
    scroll_txt.text = my_txt.scroll+" of "+my_txt.maxscroll;
};
scrollDown_btn.onRelease = function() {
    my_txt.scroll++;
    scroll_txt.text = my_txt.scroll+" of "+my_txt.maxscroll;
};

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField.hscroll, TextField.maxscroll

selectable Property

public selectable : Boolean

Player version: Flash Player 6

A Boolean value that indicates whether the text field is selectable. The value true indicates that the text is selectable. The selectable property controls whether a text field is selectable, and not whether a text field is editable. A dynamic text field can be selectable even if it is not editable. If a dynamic text field is not selectable, that means you cannot select its text.

If selectable is set to false, the text in the text field does not respond to selection commands from the mouse or keyboard, and the text cannot be copied using the Copy command. If selectable is set to true, the text in the text field can be selected using the mouse or keyboard. You can select text this way even if the text field is a dynamic text field instead of an input text field. The text can be copied using the Copy command.

Example
The following example creates a selectable text field that constantly updates with the current date and time.
this.createTextField("date_txt", this.getNextHighestDepth(), 10, 10, 100, 22);
date_txt.autoSize = true;
date_txt.selectable = true;

var date_interval:Number = setInterval(updateTime, 500, date_txt);
function updateTime(my_txt:TextField) {
    my_txt.text = new Date().toString();
}

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


sharpness Property

public sharpness : Number

Player version: Flash Player 8

The sharpness of the glyph edges in this TextField instance. This property applies only if the antiAliasType property of the text field is set to "advanced". The range for sharpness is a number from -400 to 400. If you attempt to set sharpness to a value outside that range, Flash sets the property to the nearest value in the range (either -400 or 400).

Example
This example creates three text fields with sharpness set to 400, 0, and -400. It assumes that you have a font embedded in the Library with the linkage identifier set to "Times-12". To embed the font, follow these steps:
  1. Open your Library
  2. Click the Library options menu in the upper right corner of the Library
  3. Select "New Font" from the dropdown list
  4. Name the font "Times-12"
  5. Select "Times New Roman" from the font dropdown list
  6. Press the "OK" button
  7. Right-click on the newly created font and select "Linkage..."
  8. Check the "Export for ActionScript" box
  9. Accept the default identifier "Times-12" by pressing the "OK" button
var my_format:TextFormat = new TextFormat();
my_format.font = "Times-12";

var my_text1:TextField = this.createTextField("my_text1", this.getNextHighestDepth(), 10, 10, 400, 100);
my_text1.text = "This text has sharpness set to 400."
my_text1.embedFonts = true;
my_text1.antiAliasType = "advanced";
my_text1.gridFitType = "pixel";
my_text1.sharpness = 400;
my_text1.setTextFormat(my_format); 

var my_text2:TextField = this.createTextField("my_text2", this.getNextHighestDepth(), 10, 40, 400, 100);
my_text2.text = "This text has sharpness set to 0."
my_text2.embedFonts = true;
my_text2.antiAliasType = "advanced";
my_text2.gridFitType = "pixel";
my_text2.sharpness = 0;
my_text2.setTextFormat(my_format); 
    
var my_text3:TextField = this.createTextField("my_text3", this.getNextHighestDepth(), 10, 70, 400, 100);
my_text3.text = "This text has sharpness set to -400."
my_text3.embedFonts = true;
my_text3.antiAliasType = "advanced";
my_text3.gridFitType = "pixel";
my_text3.sharpness = -400;
my_text3.setTextFormat(my_format); 

If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

See also
TextField.gridFitType, TextField.antiAliasType

_soundbuftime Property

public _soundbuftime : Number

Player version: Flash Player 6

The number of seconds a sound prebuffers before it starts to stream.

Note: Although you can specify this property for a TextField object, it is actually a global property that applies to all sounds loaded, and you can specify its value simply as _soundbuftime. Setting this property for a TextField object actually sets the global property.

For more information and an example, see the _soundbuftime global property.

See also
_soundbuftime global property

styleSheet Property

public styleSheet : StyleSheet

Player version: Flash Player 7

Attaches a style sheet to the text field. For information on creating style sheets, see the TextField.StyleSheet class entry.

The style sheet associated with a text field may be changed at any time. If the style sheet in use is changed, the text field is redrawn using the new style sheet. The style sheet may be set to null or undefined to remove the style sheet. If the style sheet in use is removed, the text field is redrawn without a style sheet. The formatting done by a style sheet is not retained if the style sheet is removed.

Example
The following example creates a new text field at runtime, called news_txt. Three buttons on the Stage, css1_btn, css2_btn and clearCss_btn, are used to change the style sheet that is applied to news_txt, or clear the style sheet from the text field. Add the following ActionScript to your FLA or AS file:
this.createTextField("news_txt", this.getNextHighestDepth(), 0, 0, 300, 200);
news_txt.wordWrap = true;
news_txt.multiline = true;
news_txt.html = true;
var newsText:String = "<p class='headline'>Description</p> Method; "
    + "starts loading the CSS file into styleSheet. The load operation is asynchronous; "
    + "use the <span class='bold'>TextField.StyleSheet.onLoad</span> "
    + "callback handler to determine when the file has finished loading. "
    + "<span class='important'>The CSS file must reside in exactly the same "
    + "domain as the SWF file that is loading it.</span> For more information about "
    + "restrictions on loading data across domains, see Flash Player security features.";

news_txt.htmlText = newsText;

css1_btn.onRelease = function() {
    var styleObj:TextField.StyleSheet = new TextField.StyleSheet();
    styleObj.onLoad = function(success:Boolean) {
    if (success) {
        news_txt.styleSheet = styleObj;
        news_txt.htmlText = newsText;
    }
    };
    styleObj.load("styles.css");
};

css2_btn.onRelease = function() {
    var styleObj:TextField.StyleSheet = new TextField.StyleSheet();
    styleObj.onLoad = function(success:Boolean) {
    if (success) {
        news_txt.styleSheet = styleObj;
        news_txt.htmlText = newsText;
    }
    };
    styleObj.load("styles2.css");
};

clearCss_btn.onRelease = function() {
    news_txt.styleSheet = undefined;
    news_txt.htmlText = newsText;
};

The following styles are applied to the text field. Save the following two CSS files in the same directory as the FLA or AS file you created previously:

// in styles.css 
.important {
    color: #FF0000;
}
.bold {
    font-weight: bold;
}
.headline {
    color: #000000;
    font-family: Arial,Helvetica,sans-serif;
    font-size: 18px;
    font-weight: bold;
    display: block;
}

// in styles2.css 
.important {
    color: #FF00FF;
}
.bold {
    font-weight: bold;
}
.headline {
    color: #00FF00;
    font-family: Arial,Helvetica,sans-serif;
    font-size: 18px;
    font-weight: bold;
    display: block;
}

If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

See also
TextField.StyleSheet

tabEnabled Property

public tabEnabled : Boolean

Player version: Flash Player 6

Specifies whether the text field is included in automatic tab ordering. It is undefined by default.

If the tabEnabled property is undefined or true, the object is included in automatic tab ordering. If the tabIndex property is also set to a value, the object is included in custom tab ordering as well. If tabEnabled is false, the object is not included in automatic or custom tab ordering, even if the tabIndex property is set.

Example
The following example creates several text fields, called one_txt, two_txt, three_txt and four_txt. The three_txt text field has the tabEnabled property set to false, so it is excluded from the automatic tab ordering.
this.createTextField("one_txt", this.getNextHighestDepth(), 10, 10, 100, 22);
one_txt.border = true;
one_txt.type = "input";
this.createTextField("two_txt", this.getNextHighestDepth(), 10, 40, 100, 22);
two_txt.border = true;
two_txt.type = "input";
this.createTextField("three_txt", this.getNextHighestDepth(), 10, 70, 100, 22);
three_txt.border = true;
three_txt.type = "input";
this.createTextField("four_txt", this.getNextHighestDepth(), 10, 100, 100, 22);
four_txt.border = true;
four_txt.type = "input";

three_txt.tabEnabled = false;
three_txt.text = "tabEnabled = false;";

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
Button.tabEnabled, MovieClip.tabEnabled

tabIndex Property

public tabIndex : Number

Player version: Flash Player 6

Lets you customize the tab ordering of objects in a SWF file. You can set the tabIndex property on a button, movie clip, or text field instance; it is undefined by default.

If any currently displayed object in the SWF file contains a tabIndex property, automatic tab ordering is disabled, and the tab ordering is calculated from the tabIndex properties of objects in the SWF file. The custom tab ordering only includes objects that have tabIndex properties.

The tabIndex property must be a positive integer. The objects are ordered according to their tabIndex properties, in ascending order. An object with a tabIndex value of 1 precedes an object with a tabIndex value of 2. If two objects have the same tabIndex value, the one that precedes the other in the tab ordering is undefined.

The custom tab ordering defined by the tabIndex property is flat. This means that no attention is paid to the hierarchical relationships of objects in the SWF file. All objects in the SWF file with tabIndex properties are placed in the tab order, and the tab order is determined by the order of the tabIndex values. If two objects have the same tabIndex value, the one that goes first is undefined. You should not use the same tabIndex value for multiple objects.

Example
The following ActionScript dynamically creates four text fields and assigns them to a custom tab order. Add the following ActionScript to your FLA or AS file:
this.createTextField("one_txt", this.getNextHighestDepth(), 10, 10, 100, 22);
one_txt.border = true;
one_txt.type = "input";
this.createTextField("two_txt", this.getNextHighestDepth(), 10, 40, 100, 22);
two_txt.border = true;
two_txt.type = "input";
this.createTextField("three_txt", this.getNextHighestDepth(), 10, 70, 100, 22);
three_txt.border = true;
three_txt.type = "input";
this.createTextField("four_txt", this.getNextHighestDepth(), 10, 100, 100, 22);
four_txt.border = true;
four_txt.type = "input";

one_txt.tabIndex = 3;
two_txt.tabIndex = 1;
three_txt.tabIndex = 2;
four_txt.tabIndex = 4;

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
Button.tabIndex, MovieClip.tabIndex

_target Property

public _target : String  [read-only]

Player version: Flash Player 6

The target path of the text field instance. The _self target specifies the current frame in the current window, _blank specifies a new window, _parent specifies the parent of the current frame, and _top specifies the top-level frame in the current window.

Example
The following ActionScript creates a text field called my_txt and outputs the target path of the new field, in both slash and dot notation.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 100, 22);
trace(my_txt._target); // output: /my_txt
trace(eval(my_txt._target)); // output: _level0.my_txt

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


text Property

public text : String

Player version: Flash Player 6

Indicates the current text in the text field. Lines are separated by the carriage return character ("\r", ASCII 13). This property contains the normal, unformatted text in the text field, without HTML tags, even if the text field is HTML.

Example
The following example creates an HTML text field called my_txt, and assigns an HTML-formatted string of text to the field. When you trace the htmlText property, the Output panel displays the HTML-formatted string. the HTML-formatted string writes to the log file. When you trace the value of the text property, the unformatted string with HTML tags displays in the Output panel. When you trace the value of the text property, the unformatted string with HTML tags writes to the log file.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 400, 22);
my_txt.html = true;
my_txt.htmlText = "<B>Lorem ipsum dolor sit amet.</B>";

trace("htmlText: "+my_txt.htmlText);
trace("text: "+my_txt.text);

This generates the following output:


      htmlText: <P ALIGN="LEFT"><FONT FACE="Times New Roman" SIZE="12" COLOR="#000000" KERNING="0">
      <B>Lorem ipsum dolor sit amet.</B></FONT></P>
      text: Lorem ipsum dolor sit amet.
      

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField.htmlText

textColor Property

public textColor : Number

Player version: Flash Player 6

Indicates the color of the text in a text field. The hexadecimal color system uses six digits to represent color values. Each digit has sixteen possible values or characters. The characters range from 0 to 9 and then A to F. Black is represented by (#000000) and white, at the opposite end of the color system, is (#FFFFFF).

Example
The following ActionScript creates a text field and changes its color property to red.
this.createTextField("my_txt", 99, 10, 10, 100, 300);
my_txt.text = "this will be red text";
my_txt.textColor = 0xFF0000;

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


textHeight Property

public textHeight : Number

Player version: Flash Player 6

Indicates the height of the text.

Example
The following example creates a text field, and assigns a string of text to the field. A trace statement is used to display the text height and width in the Output panel.The trace() method is used to write the text height and width in the log file. The autoSize property is then used to resize the text field, and the new height and width will also be displayed in the Output panel.The autoSize property is then used to resize the text field, and the new height and width also write to the log file.
this.createTextField("my_txt", 99, 10, 10, 100, 300);
my_txt.text = "Sample text";
trace("textHeight: "+my_txt.textHeight+", textWidth: "+my_txt.textWidth);
trace("_height: "+my_txt._height+", _width: "+my_txt._width+"\n");
my_txt.autoSize = true;
trace("after my_txt.autoSize = true;");
trace("_height: "+my_txt._height+", _width: "+my_txt._width);

Which outputs the following information:

textHeight: 15, textWidth: 56
_height: 300, _width: 100

after my_txt.autoSize = true;
_height: 19, _width: 60

See also
TextField.textWidth

textWidth Property

public textWidth : Number

Player version: Flash Player 6

Indicates the width of the text.

Example
See the example for TextField.textHeight.

See also
TextField.textHeight

thickness Property

public thickness : Number

Player version: Flash Player 8

The thickness of the glyph edges in this TextField instance. This property applies only when antiAliasType() is set to "advanced".

The range for thickness is a number from -200 to 200. If you attempt to set thickness to a value outside that range, the property is set to the nearest value in the range (either -200 or 200).

Example
This example creates two text fields and applies a thickness of -200 to one and 200 to the other. It assumes that you have a font embedded in the Library with the linkage identifier set to "Times-12". To embed the font, follow these steps:
  1. Open your Library
  2. Click the Library options menu in the upper right corner of the Library
  3. Select "New Font" from the dropdown list
  4. Name the font "Times-12"
  5. Select "Times New Roman" from the font dropdown list
  6. Press the "OK" button
  7. Right-click on the newly created font and select "Linkage..."
  8. Check the "Export for ActionScript" box
  9. Accept the default identifier "Times-12" by pressing the "OK" button
var my_format:TextFormat = new TextFormat();
my_format.font = "Times-12";

var my_text1:TextField = this.createTextField("my_text1", this.getNextHighestDepth(), 10, 10, 300, 30);
my_text1.text = "thickness = 200";
my_text1.antiAliasType = "advanced";
my_text1.border = true;
my_text1.thickness = 200;
my_text1.embedFonts = true;
my_text1.setTextFormat(my_format); 

var my_text2:TextField = this.createTextField("my_text2", this.getNextHighestDepth(), 10, 50, 300, 30);
my_text2.text = "thickness = -200."
my_text2.antiAliasType = "advanced";
my_text2.thickness = -200;
my_text2.border = true;
my_text2.embedFonts = true;
my_text2.setTextFormat(my_format);         

If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

See also
TextField.antiAliasType

type Property

public type : String

Player version: Flash Player 6

Specifies the type of text field. There are two values: "dynamic", which specifies a dynamic text field that cannot be edited by the user, and "input", which specifies an input text field.

Example
The following example creates two text fields: username_txt and password_txt. Text is entered into both text fields; however, password_txt has the password property set to true. Therefore, the characters display as asterisks instead of as characters in the password_txt field.
this.createTextField("username_txt", this.getNextHighestDepth(), 10, 10, 100, 22);
username_txt.border = true;
username_txt.type = "input";
username_txt.maxChars = 16;
username_txt.text = "hello";

this.createTextField("password_txt", this.getNextHighestDepth(), 10, 40, 100, 22);
password_txt.border = true;
password_txt.type = "input";
password_txt.maxChars = 16;
password_txt.password = true;
password_txt.text = "world";

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


_url Property

public _url : String  [read-only]

Player version: Flash Player 6

Retrieves the URL of the SWF file that created the text field.

Example
The following example retrieves the URL of the SWF file that created the text field, and a SWF file that loads into it.
this.createTextField("my_txt", 1, 10, 10, 100, 22);
trace(my_txt._url);

var mclListener:Object = new Object();
mclListener.onLoadInit = function(target_mc:MovieClip) {
    trace(target_mc._url);
};
var holder_mcl:MovieClipLoader = new MovieClipLoader();
holder_mcl.addListener(mclListener);
holder_mcl.loadClip("best_flash_ever.swf", this.createEmptyMovieClip("holder_mc", 2));

When you test this example, the URL of the SWF file you are testing, and the file called best_flash_ever.swf are displayed in the Output panel. When you test this example, the URL of the SWF file you are testing, and the file called best_flash_ever.swf write to the log file.

The MovieClipLoader class used in this example requires Flash Player 7 or later.


variable Property

public variable : String

Player version: Flash Player 6

The name of the variable that the text field is associated with. The type of this property is String.

Example
The following example creates a text field called my_txt and associates the variable today_date with the text field. When you change the variable today_date, then the text that displays in my_txt updates.
this.createTextField("my_txt", 1, 10, 10, 200, 22);
my_txt.variable = "today_date";
var today_date:Date = new Date();

var date_interval:Number = setInterval(updateDate, 500);
function updateDate():Void {
    today_date = new Date();
}


_visible Property

public _visible : Boolean

Player version: Flash Player 6

A Boolean value that indicates whether the text field my_txt is visible. Text fields that are not visible (_visible property set to false) are disabled.

Example
The following example creates a text field called my_txt. A button called visible_btn toggles the visibility of my_txt.
this.createTextField("my_txt", 1, 10, 10, 200, 22);
my_txt.background = true;
my_txt.backgroundColor = 0xDFDFDF;
my_txt.border = true;
my_txt.type = "input";

visible_btn.onRelease = function() {
    my_txt._visible = !my_txt._visible;
};

See also
Button._visible, MovieClip._visible

_width Property

public _width : Number

Player version: Flash Player 6

The width of the text field, in pixels.

Example
The following example creates two text fields that you can use to change the width and height of a third text field on the Stage. Add the following ActionScript to a FLA or AS file.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 40, 160, 120);
my_txt.background = true;
my_txt.backgroundColor = 0xFF0000;
my_txt.border = true;
my_txt.multiline = true;
my_txt.type = "input";
my_txt.wordWrap = true;

this.createTextField("width_txt", this.getNextHighestDepth(), 10, 10, 30, 20);
width_txt.border = true;
width_txt.maxChars = 3;
width_txt.restrict = "0-9";
width_txt.type = "input";
width_txt.text = my_txt._width;
width_txt.onChanged = function() {
    my_txt._width = this.text;
}

this.createTextField("height_txt", this.getNextHighestDepth(), 70, 10, 30, 20);
height_txt.border = true;
height_txt.maxChars = 3;
height_txt.restrict = "0-9";
height_txt.type = "input";
height_txt.text = my_txt._height;
height_txt.onChanged = function() {
    my_txt._height = this.text;
}

When you test the example, try entering new values into width_txt and height_txt to change the dimensions of my_txt.

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField._height

wordWrap Property

public wordWrap : Boolean

Player version: Flash Player 6

A Boolean value that indicates if the text field has word wrap. If the value of wordWrap is true, the text field has word wrap; if the value is false, the text field does not have word wrap.

Example
The following example demonstrates how wordWrap affects long text in a text field that is created at runtime.
this.createTextField("my_txt", 99, 10, 10, 100, 200);
my_txt.text = "This is very long text that will certainly extend beyond the width of this text field";
my_txt.border = true;

Test the SWF file in Flash Player by selecting Control > Test Movie. Then return to your ActionScript and add the following line to the code and test the SWF file again:

my_txt.wordWrap = true;


_x Property

public _x : Number

Player version: Flash Player 6

An integer that sets the x coordinate of a text field relative to the local coordinates of the parent movie clip. If a text field is on the main Timeline, then its coordinate system refers to the upper left corner of the Stage as (0, 0). If the text field is inside a movie clip that has transformations, the text field is in the local coordinate system of the enclosing movie clip. Thus, for a movie clip rotated 90 degrees counterclockwise, the enclosed text field inherits a coordinate system that is rotated 90 degrees counterclockwise. The text field's coordinates refer to the registration point position.

Example
The following example creates a text field wherever you click the mouse. When it creates a text field, that field displays the current x and y coordinates of the text field.
this.createTextField("coords_txt", this.getNextHighestDepth(), 0, 0, 60, 22);
coords_txt.autoSize = true;
coords_txt.selectable = false;
coords_txt.border = true;

var mouseListener:Object = new Object();
mouseListener.onMouseDown = function() {
    coords_txt.text = "X:"+Math.round(_xmouse)+", Y:"+Math.round(_ymouse);
    coords_txt._x = _xmouse;
    coords_txt._y = _ymouse;
};
Mouse.addListener(mouseListener);

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField._xscale, TextField._y, TextField._yscale

_xmouse Property

public _xmouse : Number  [read-only]

Player version: Flash Player 6

Returns the x coordinate of the mouse position relative to the text field.

Example
The following example creates three text fields on the Stage. The mouse_txt instance displays the current position of the mouse in relation to the Stage. The textfield_txt instance displays the current position of the mouse pointer in relation to the my_txt instance. Add the following ActionScript to a FLA or AS file:
this.createTextField("mouse_txt", this.getNextHighestDepth(), 10, 10, 200, 22);
mouse_txt.border = true;
this.createTextField("textfield_txt", this.getNextHighestDepth(), 220, 10, 200, 22);
textfield_txt.border = true;
this.createTextField("my_txt", this.getNextHighestDepth(), 100, 100, 160, 120);
my_txt.border = true;

var mouseListener:Object = new Object();
mouseListener.onMouseMove = function() {
    mouse_txt.text = "MOUSE ... X:" + Math.round(_xmouse) + ",\tY:" + Math.round(_ymouse);
    textfield_txt.text = "TEXTFIELD ... X:" + Math.round(my_txt._xmouse) + ",\tY:" +
    Math.round(my_txt._ymouse);
}

Mouse.addListener(mouseListener);

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField._ymouse

_xscale Property

public _xscale : Number

Player version: Flash Player 6

Determines the horizontal scale of the text field as applied from the registration point of the text field, expressed as a percentage. The default registration point is (0,0).

Example
The following example scales the my_txt instance when you click the scaleUp_btn and scaleDown_btn instances.
this.createTextField("my_txt", 99, 10, 40, 100, 22);
my_txt.autoSize = true;
my_txt.border = true;
my_txt.selectable = false;
my_txt.text = "Sample text goes here.";

scaleUp_btn.onRelease = function() {
    my_txt._xscale = 2;
    my_txt._yscale = 2;
}
scaleDown_btn.onRelease = function() {
    my_txt._xscale /= 2;
    my_txt._yscale /= 2;
}

See also
TextField._x, TextField._y, TextField._yscale

_y Property

public _y : Number

Player version: Flash Player 6

The y coordinate of a text field relative to the local coordinates of the parent movie clip. If a text field is in the main Timeline, then its coordinate system refers to the upper left corner of the Stage as (0, 0). If the text field is inside another movie clip that has transformations, the text field is in the local coordinate system of the enclosing movie clip. Thus, for a movie clip rotated 90 degrees counterclockwise, the enclosed text field inherits a coordinate system that is rotated 90 degrees counterclockwise. The text field's coordinates refer to the registration point position.

Example
See the example for TextField._x.

See also
TextField._x, TextField._xscale, TextField._yscale

_ymouse Property

public _ymouse : Number  [read-only]

Player version: Flash Player 6

Indicates the y coordinate of the mouse position relative to the text field.

Example
See the example for TextField._xmouse.

See also
TextField._xmouse

_yscale Property

public _yscale : Number

Player version: Flash Player 6

The vertical scale of the text field as applied from the registration point of the text field, expressed as a percentage. The default registration point is (0,0).

Example
See the example for TextField._xscale.

See also
TextField._x, TextField._xscale, TextField._y


Event Detail

onChanged Event Handler

public onChanged = function(changedField:TextField) {}

Player version: Flash Player 6

Event handler/listener; invoked when the content of a text field changes. By default, it is undefined; you can define it in a script.

A reference to the text field instance is passed as a parameter to the onChanged handler. You can capture this data by putting a parameter in the event handler method. For example, the following code uses textfield_txt as the parameter that is passed to the onChanged event handler. The parameter is then used in a trace() statement to send the instance name of the text field to the Output panel: The parameter is then used in a trace() method to write the instance name of the text field to the log file:

this.createTextField("myInputText_txt", 99, 10, 10, 300, 20);
myInputText_txt.border = true;
myInputText_txt.type = "input";

myInputText_txt.onChanged = function(textfield_txt:TextField) {
trace("the value of "+textfield_txt._name+" was changed. New value is: "+textfield_txt.text);
};

The onChanged handler is called only when the change results from user interaction; for example, when the user is typing something on the keyboard, changing something in the text field using the mouse, or selecting a menu item. Programmatic changes to the text field do not trigger the onChanged event because the code recognizes changes that are made to the text field.

Parameters
changedField:TextField — The field triggering the event.

See also
TextFormat, TextField.setNewTextFormat()

onKillFocus Event Handler

public onKillFocus = function(newFocus:Object) {}

Player version: Flash Player 6

Invoked when a text field loses keyboard focus. The onKillFocus method receives one parameter, newFocus, which is an object representing the new object receiving the focus. If no object receives the focus, newFocus contains the value null.

Parameters
newFocus:Object — The object that is receiving the focus.

Example
The following example creates two text fields called first_txt and second_txt. When you give focus to a text field, information about the text field with current focus and the text field that lost focus is displayed in the Output panel. When you give focus to a text field, information about the text field with current focus and the text field that lost focus writes to the log file.
this.createTextField("first_txt", 1, 10, 10, 300, 20);
first_txt.border = true;
first_txt.type = "input";
this.createTextField("second_txt", 2, 10, 40, 300, 20);
second_txt.border = true;
second_txt.type = "input";
first_txt.onKillFocus = function(newFocus:Object) {
    trace(this._name+" lost focus. New focus changed to: "+newFocus._name);
};
first_txt.onSetFocus = function(oldFocus:Object) {
    trace(this._name+" gained focus. Old focus changed from: "+oldFocus._name);
}

See also
TextField.onSetFocus

onScroller Event Handler

public onScroller = function(scrolledField:TextField) {}

Player version: Flash Player 6

Event handler/listener; invoked when one of the text field scroll properties changes.

A reference to the text field instance is passed as a parameter to the onScroller handler. You can capture this data by putting a parameter in the event handler method. For example, the following code uses my_txt as the parameter that is passed to the onScroller event handler. The parameter is then used in a trace() statement to send the instance name of the text field to the Output panel. The parameter is then used in a trace() method to write the instance name of the text field to the log file.

myTextField.onScroller = function (my_txt:TextField) {
    trace (my_txt._name + " scrolled");
};

The TextField.onScroller event handler is commonly used to implement scroll bars. Scroll bars typically have a thumb or other indicator that shows the current horizontal or vertical scrolling position in a text field. Text fields can be navigated using the mouse and keyboard, which causes the scroll position to change. The scroll bar code needs to be notified if the scroll position changes because of such user interaction, which is what TextField.onScroller is used for.

onScroller is called whether the scroll position changed because of a users interaction with the text field, or programmatic changes. The onChanged handler fires only if a user interaction causes the change. These two options are necessary because often one piece of code changes the scrolling position, while the scroll bar code is unrelated and won't know that the scroll position changed without being notified.

Parameters
scrolledField:TextField — A reference to the TextField object whose scroll position was changed.

Example
The following example creates a text field called my_txt, and uses two buttons called scrollUp_btn and scrollDown_btn to scroll the contents of the text field. When the onScroller event handler is called, a trace statement is used to display information in the Output panel. When the onScroller event handler is called, a trace() method is used to write information to the log file. Create two buttons with instance names scrollUp_btn and scrollDown_btn, and add the following ActionScript to your FLA or AS file:
this.createTextField("scroll_txt", this.getNextHighestDepth(), 10, 10, 160, 20);
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 30, 320, 240);
my_txt.multiline = true;
my_txt.wordWrap = true;

for (var i = 0; i<10; i++) {
    my_txt.text += "Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam "
        + "nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.";
}
scrollUp_btn.onRelease = function() {
    my_txt.scroll--;
};
scrollDown_btn.onRelease = function() {
    my_txt.scroll++;
};
my_txt.onScroller = function() {
        trace("onScroller called");
    scroll_txt.text = my_txt.scroll+" of "+my_txt.maxscroll;
};

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField.hscroll, TextField.maxhscroll, TextField.maxscroll, TextField.scroll

onSetFocus Event Handler

public onSetFocus = function(oldFocus:Object) {}

Player version: Flash Player 6

Invoked when a text field receives keyboard focus. The oldFocus parameter is the object that loses the focus. For example, if the user presses the Tab key to move the input focus from a button to a text field, oldFocus contains the button instance. If there is no previously focused object, oldFocus contains a null value.

Parameters
oldFocus:Object — The object to lose focus.

Example
See the example for TextField.onKillFocus.

See also
TextField.onKillFocus


Method Detail

addListener Method

public addListener(listener:Object) : Boolean

Player version: Flash Player 6

Registers an object to receive TextField event notifications. The object will receive event notifications whenever the onChanged and onScroller event handlers have been invoked. When a text field changes or is scrolled, the TextField.onChanged and TextField.onScroller event handlers are invoked, followed by the onChanged and onScroller event handlers of any objects registered as listeners. Multiple objects can be registered as listeners.

To remove a listener object from a text field, call TextField.removeListener().

A reference to the text field instance is passed as a parameter to the onScroller and onChanged handlers by the event source. You can capture this data by putting a parameter in the event handler method. For example, the following code uses txt as the parameter that is passed to the onScroller event handler. The parameter is then used in a trace statement to send the instance name of the text field to the Output panel.The parameter is then used in a trace() method to write the instance name of the text field to the log file.

my_txt.onScroller = function(textfield_txt:TextField) {
    trace(textfield_txt._name+" scrolled");
};

Parameters
listener:Object — An object with an onChanged or onScroller event handler.

Returns
Boolean

Example
The following example defines an onChanged handler for the input text field my_txt. It then defines a new listener object, txtListener, and defines an onChanged handler for that object. This handler will be invoked when the text field my_txt is changed. The final line of code calls TextField.addListener to register the listener object txtListener with the text field my_txt so that it will be notified when my_txt changes.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 100, 22);
my_txt.border = true;
my_txt.type = "input";

my_txt.onChanged = function(textfield_txt:TextField) {
    trace(textfield_txt._name+" changed");
};
var txtListener:Object = new Object();
txtListener.onChanged = function(textfield_txt:TextField) {
    trace(textfield_txt._name+" changed and notified myListener");
};
my_txt.addListener(txtListener);

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField.onChanged, TextField.onScroller, TextField.removeListener()

getDepth Method

public getDepth() : Number

Player version: Flash Player 6

Returns the depth of a text field.

Returns
Number — An integer that represents the depth of the text field.

Example
The following example demonstrates text fields that reside at different depths. Create a dynamic text field on the Stage and add the following ActionScript code to your FLA or AS file. The code dynamically creates two text fields at runtime and outputs their depths.
this.createTextField("first_mc", this.getNextHighestDepth(), 10, 10, 100, 22);
this.createTextField("second_mc", this.getNextHighestDepth(), 10, 10, 100, 22);
for (var prop in this) {
    if (this[prop] instanceof TextField) {
    var this_txt:TextField = this[prop];
    trace(this_txt._name+" is a TextField at depth: "+this_txt.getDepth());
    }
}

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


getFontList Method

public static getFontList() : Array

Player version: Flash Player 6

Returns the names of fonts on the player's host system as an array. (This method does not return names of all fonts in currently loaded SWF files.) The names are of type String. This method is a static method of the global TextField class. You cannot specify a text field instance when you call this method.

Returns
Array — An array of font names.

Example
The following code displays a font list returned by getFontList():
var font_array:Array = TextField.getFontList();
font_array.sort();
trace("You have "+font_array.length+" fonts currently installed");
trace("--------------------------------------");
for (var i = 0; i<font_array.length; i++) {
    trace("Font #"+(i+1)+":\t"+font_array[i]);
}


getNewTextFormat Method

public getNewTextFormat() : TextFormat

Player version: Flash Player 6

Returns a TextFormat object containing a copy of the text field's text format object. The text format object is the format that newly inserted text, such as text inserted with the replaceSel() method or text entered by a user, receives. When getNewTextFormat() is invoked, the TextFormat object returned has all of its properties defined. No property is null.

Returns
TextFormat — A TextFormat object.

Example
The following example displays the specified text field's (my_txt) text format object.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 160, 120);
var my_fmt:TextFormat = my_txt.getNewTextFormat();
trace("TextFormat has the following properties:");
for (var prop in my_fmt) {
    trace(prop+": "+my_fmt[prop]);
}

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


getTextFormat Method

public getTextFormat([beginIndex:Number], [endIndex:Number]) : TextFormat

Player version: Flash Player 6

Returns a TextFormat object for a character, a range of characters, or an entire TextField object.

The following table describes three possible usages:

Usage Description
my_textField.getTextFormat() Returns a TextFormat object containing formatting information for all text in a text field. Only properties that are common to all text in the text field are set in the resulting TextFormat object. Any property that is mixed, meaning that it has different values at different points in the text, has a value of null.
my_textField.getTextFormat(beginIndex:Number) Returns a TextFormat object containing a copy of the text field's text format at the beginIndex position.
my_textField.getTextFormat(beginIndex:Number,endIndex:Number) Returns a TextFormat object containing formatting information for the span of text from beginIndex to endIndex. Only properties that are common to all of the text in the specified range are set in the resulting TextFormat object. Any property that is mixed (that is, has different values at different points in the range) has its value set to null.

Parameters
beginIndex:Number [optional] — An integer that specifies a character in a string. If you do not specify beginIndex and endIndex, the TextFormat object returned is for the entire TextField.
endIndex:Number [optional] — An integer that specifies the end position of a span of text. If you specify beginIndex but do not specify endIndex, the TextFormat returned is for the single character specified by beginIndex.

Returns
TextFormat — The TextFormat object that represents the formatting properties for the specified text.

Example
The following ActionScript code traces all of the formatting information for a text field that is created at runtime.
this.createTextField("dyn_txt", this.getNextHighestDepth(), 0, 0, 100, 200);
dyn_txt.text = "Frank";
dyn_txt.setTextFormat(new TextFormat());
var my_fmt:TextFormat = dyn_txt.getTextFormat();
for (var prop in my_fmt) {
    trace(prop+": "+my_fmt[prop]);
}

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextField.getNewTextFormat(), TextField.setNewTextFormat(), TextField.setTextFormat()

removeListener Method

public removeListener(listener:Object) : Boolean

Player version: Flash Player 6

Removes a listener object previously registered to a text field instance with TextField.addListener().

Parameters
listener:Object — The object that will no longer receive notifications from TextField.onChanged or TextField.onScroller.

Returns
Boolean — If listener was successfully removed, the method returns a true value. If listener was not successfully removed (for example, if listener was not on the TextField object's listener list), the method returns a value of false.

Example
The following example creates an input text field called my_txt. When the user types into the field, information about the number of characters in the text field is displayed in the Output panel. If the user clicks the removeListener_btn instance, then the listener is removed and information is no longer displayed.When the user types into the field, information about the number of characters in the text field writes to the log file. If the user clicks the removeListener_btn instance, then the listener is removed and information no longer writes to the log file.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 160, 20);
my_txt.border = true;
my_txt.type = "input";

var txtListener:Object = new Object();
txtListener.onChanged = function(textfield_txt:TextField) {
    trace(textfield_txt+" changed. Current length is: "+textfield_txt.length);
};
my_txt.addListener(txtListener);

removeListener_btn.onRelease = function() {
    trace("Removing listener...");
    if (!my_txt.removeListener(txtListener)) {
    trace("Error! Unable to remove listener");
    }
};

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


removeTextField Method

public removeTextField() : Void

Player version: Flash Player 6

Removes the text field. This operation can only be performed on a text field that was created with MovieClip.createTextField(). When you call this method, the text field is removed. This method is similar to MovieClip.removeMovieClip().

Example
The following example creates a text field that you can remove from the Stage when you click the remove_btn instance. Create a button and call it remove_btn, and then add the following ActionScript to your FLA or AS file.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 300, 22);
my_txt.text = new Date().toString();
my_txt.border = true;

remove_btn.onRelease = function() {
    my_txt.removeTextField();
};

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.


replaceSel Method

public replaceSel(newText:String) : Void

Player version: Flash Player 6

Replaces the current selection with the contents of the newText parameter. The text is inserted at the position of the current selection, using the current default character format and default paragraph format. The text is not treated as HTML, even if the text field is an HTML text field.

You can use the replaceSel() method to insert and delete text without disrupting the character and paragraph formatting of the rest of the text.

You must use Selection.setFocus() to focus the field before issuing this command.

Parameters
newText:String — A string.

Example
The following example code creates a multiline text field with text on the Stage. When you select some text and then right-click or Control-click over the text field, you can select Enter current date from the context menu. This selection calls a function that replaces the selected text with the current date.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 320, 240);
my_txt.border = true;
my_txt.wordWrap = true;
my_txt.multiline = true;
my_txt.type = "input";
my_txt.text = "Select some sample text from the text field and then right-click/control click "
        + "and select 'Enter current date' from the context menu to replace the "
        + "currently selected text with the current date.";

var my_cm:ContextMenu = new ContextMenu();
my_cm.customItems.push(new ContextMenuItem("Enter current date", enterDate));
function enterDate(obj:Object, menuItem:ContextMenuItem) {
    var today_str:String = new Date().toString();
    var date_str:String = today_str.split(" ", 3).join(" ");
    my_txt.replaceSel(date_str);
}
my_txt.menu = my_cm;

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
Selection.setFocus()

replaceText Method

public replaceText(beginIndex:Number, endIndex:Number, newText:String) : Void

Player version: Flash Player 7

Replaces a range of characters, specified by the beginIndex and endIndex parameters, in the specified text field with the contents of the newText parameter.

Parameters
beginIndex:Number — The start index value for the replacement range.
endIndex:Number — The end index value for the replacement range.
newText:String — The text to use to replace the specified range of characters.

Example
The following example creates a text field called my_txt and assigns the text dog@house.net to the field. The indexOf() method is used to find the first occurrence of the specified symbol (@). If the symbol is found, the specified text (between the index of 0 and the symbol) replaces with the string bird. If the symbol is not found, an error message is displayed in the Output panel.If the symbol is not found, an error message writes to the log file.
this.createTextField("my_txt", this.getNextHighestDepth(), 10, 10, 320, 22);
my_txt.autoSize = true;
my_txt.text = "dog@house.net";

var symbol:String = "@";
var symbolPos:Number = my_txt.text.indexOf(symbol);
if (symbolPos>-1) {
    my_txt.replaceText(0, symbolPos, "bird");
} else {
    trace("symbol '"+symbol+"' not found.");
}

If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.


setNewTextFormat Method

public setNewTextFormat(tf:TextFormat) : Void

Player version: Flash Player 6

Sets the default new text format of a text field. The default new text format is the new text format used for newly inserted text such as text inserted with the replaceSel() method or text entered by a user. When text is inserted, the newly inserted text is assigned the default new text format.

The new default text format is specified by textFormat, which is a TextFormat object.

Parameters
tf:TextFormat — A TextFormat object.

Example
In the following example, a new text field (called my_txt) is created at runtime and several properties are set. The format of the newly inserted text is applied.
var my_fmt:TextFormat = new TextFormat();
my_fmt.bold = true;
my_fmt.font = "Arial";
my_fmt.color = 0xFF9900;

this.createTextField("my_txt", 999, 0, 0, 400, 300);
my_txt.wordWrap = true;
my_txt.multiline = true;
my_txt.border = true;
my_txt.type = "input";
my_txt.setNewTextFormat(my_fmt);
my_txt.text = "Oranges are a good source of vitamin C";

See also
TextField.getNewTextFormat(), TextField.getTextFormat(), TextField.setTextFormat()

setTextFormat Method

public setTextFormat([beginIndex:Number], [endIndex:Number], textFormat:TextFormat) : Void

Player version: Flash Player 6

Applies the text formatting specified by the textFormat parameter to some or all of the text in a text field. textFormat must be a TextFormat object that specifies the text formatting changes desired. Only the non-null properties of textFormat are applied to the text field. Any property of textFormat that is set to null will not be applied. By default, all of the properties of a newly created TextFormat object are set to null.

There are two types of formatting information in a TextFormat object: character level, and paragraph level formatting. Each character in a text field might have its own character formatting settings, such as font name, font size, bold, and italic.

For paragraphs, the first character of the paragraph is examined for the paragraph formatting settings for the entire paragraph. Examples of paragraph formatting settings are left margin, right margin, and indentation.

The setTextFormat() method changes the text formatting applied to an individual character, to a range of characters, or to the entire body of text in a text field. These usages are shown in the following table:

Usage Description
my_textField.setTextFormat(textFormat:TextFormat) Applies the properties of textFormat to all text in the text field.
my_textField.setTextFormat(beginIndex:Number, textFormat:TextFormat) Applies the properties of textFormat to the character at the beginIndex position.
my_textField.setTextFormat(beginIndex:Number, endIndex:Number, textFormat:TextFormat) Applies the properties of the textFormat parameter to the span of text from the beginIndex position to the endIndex position.

Notice that any text inserted manually by the user, or replaced by means of TextField.replaceSel(), receives the text field's default formatting for new text, and not the formatting specified for the text insertion point. To set a text field's default formatting for new text, use TextField.setNewTextFormat().

Parameters
beginIndex:Number [optional] — An integer that specifies the first character of the desired text span. If you do not specify beginIndex and endIndex, the TextFormat is applied to the entire TextField.
endIndex:Number [optional] — An integer that specifies the first character after the desired text span. If you specify beginIndex but do not specify endIndex, the TextFormat is applied to the single character specified by beginIndex.
textFormat:TextFormat — A TextFormat object, which contains character and paragraph formatting information.

Example
The following example sets the text format for two different strings of text. The setTextFormat() method is called and applied to the my_txt text field.
var format1_fmt:TextFormat = new TextFormat();
format1_fmt.font = "Arial";
var format2_fmt:TextFormat = new TextFormat();
format2_fmt.font = "Courier";

var string1:String = "Sample string number one."+newline;
var string2:String = "Sample string number two."+newline;

this.createTextField("my_txt", this.getNextHighestDepth(), 0, 0, 300, 200);
my_txt.multiline = true;
my_txt.wordWrap = true;
my_txt.text = string1;
var firstIndex:Number = my_txt.length;
my_txt.text += string2;
var secondIndex:Number = my_txt.length;

my_txt.setTextFormat(0, firstIndex, format1_fmt);
my_txt.setTextFormat(firstIndex, secondIndex, format2_fmt);

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also
TextFormat, TextField.setNewTextFormat()