class flash.text.TextField extends InteractiveObject
Available on all platforms
The TextField class is used to create display objects for text display and
* input. To create a text field dynamically, use the 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. You can apply Cascading Style Sheets(CSS) styles to
* text fields by using the Flash Player supports a subset of HTML tags that you can use to format
* text. See the list of supported HTML tags in the description of the
* Note: The default behavior,
* adding the text to the text field, occurs
* only when Flash Player generates the
* event, which in this case happens when a
* user attempts to input text. You cannot
* put text into a text field by sending it
* TextField()
* constructor.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
* optionally uses CSS styles, directly to a text field. HTML text that you
* assign to a text field can contain embedded media(movie clips, SWF files,
* GIF files, PNG files, and JPEG 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. htmlText
property.textInput
event, which is
* dispatched before the value is modified.
* Unlike the W3C DOM Event Model version of
* the change
event, which
* dispatches the event only after the
* control loses focus, the ActionScript 3.0
* version of the change
event
* is dispatched any time the control
* changes. For example, if a user types text
* into a text field, a change
* event is dispatched after every keystroke.
* @event link Dispatched when a user clicks a hyperlink
* in an HTML-enabled text field, where the
* URL begins with "event:". The remainder of
* the URL after "event:" is placed in the
* text property of the LINK event.
*
* textInput
events.textInput
event when a user
* enters one or more characters of text.
* Various text input methods can generate
* this event, including standard keyboards,
* input method editors(IMEs), voice or
* speech recognition systems, and even the
* act of pasting plain text with no
* formatting or style information.
* @event textInteractionModeChange Flash Player dispatches the
* textInteractionModeChange
* event when a user changes the interaction
* mode of a text field. for example on
* Android, one can toggle from NORMAL mode
* to SELECTION mode using context menu
* options
Class Fields
static function isFontCompatible(fontName:String, fontStyle:String):Bool
Returns true if an embedded font is available with the specified
* TextField cannot use a font of type fontName
and fontStyle
where
* Font.fontType
is flash.text.FontType.EMBEDDED
.
* Starting with Flash Player 10, two kinds of embedded fonts can appear in a
* SWF file. Normal embedded fonts are only used with TextField objects. CFF
* embedded fonts are only used with the flash.text.engine classes. The two
* types are distinguished by the fontType
property of the
* Font
class, as returned by the enumerateFonts()
* function.
* EMBEDDEDCFF
. If
* embedFonts
is set to true
and the only font
* available at run time with the specified name and style is of type
* EMBEDDED
If both EMBEDDED
and EMBEDDED_CFF
fonts are
* available with the same name and style, the EMBEDDED
font is
* selected and text renders with the EMBEDDED
font.
fontName | The name of the embedded font to check. * |
fontStyle | Specifies the font style to check. Use
|
returns | true if a compatible embedded font is available,
* otherwise false .
* |
Instance Fields
When set to true
and the text field is not in focus, Flash
* Player highlights the selection in the text field in gray. When set to
* false
and the text field is not in focus, Flash Player does
* not highlight the selection in the text field.
*
* @default false
var antiAliasType:AntiAliasType
The type of anti-aliasing used for this text field. Use
* flash.text.AntiAliasType
constants for this property. You can
* control this setting only if the font is embedded(with the
* embedFonts
property set to true
). The default
* setting is flash.text.AntiAliasType.NORMAL
.
*
*
To set values for this property, use the following string values:
var autoSize:TextFieldAutoSize
Controls automatic sizing and alignment of text fields. Acceptable values
* for the If TextFieldAutoSize
constants:
* TextFieldAutoSize.NONE
(the default),
* TextFieldAutoSize.LEFT
, TextFieldAutoSize.RIGHT
,
* and TextFieldAutoSize.CENTER
.
* autoSize
is set to TextFieldAutoSize.NONE
* (the default) no resizing occurs.
If autoSize
is set to TextFieldAutoSize.LEFT
,
* the text is treated as left-justified text, meaning that the left margin
* of the text field remains fixed and any resizing of a single line of the
* text field is on the right margin. If the text includes a line break(for
* example, "\n"
or "\r"
), the bottom is also
* resized to fit the next line of text. If wordWrap
is also set
* to true
, only the bottom of the text field is resized and the
* right side remains fixed.
If autoSize
is set to
* TextFieldAutoSize.RIGHT
, the text is treated as
* right-justified text, meaning that the right margin of the text field
* remains fixed and any resizing of a single line of the text field is on
* the left margin. If the text includes a line break(for example,
* "\n" or "\r")
, the bottom is also resized to fit the next
* line of text. If wordWrap
is also set to true
,
* only the bottom of the text field is resized and the left side remains
* fixed.
If autoSize
is set to
* TextFieldAutoSize.CENTER
, the text is treated as
* center-justified text, meaning that any resizing of a single line of the
* text field is equally distributed to both the right and left margins. If
* the text includes a line break(for example, "\n"
or
* "\r"
), the bottom is also resized to fit the next line of
* text. If wordWrap
is also set to true
, only the
* bottom of the text field is resized and the left and right sides remain
* fixed.
var background:Bool
Specifies whether 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. Use the
* backgroundColor
property to set the background color of a
* text field.
*
* @default false
var backgroundColor:UInt
The color of the text field background. The default value is
* 0xFFFFFF
(white). This property can be retrieved or set, even
* if there currently is no background, but the color is visible only if the
* text field has the background
property set to
* true
.
Specifies whether the text field has a border. If true
, the
* text field has a border. If false
, the text field has no
* border. Use the borderColor
property to set the border color.
*
* @default false
var borderColor:UInt
The color of the text field border. The default value is
* 0x000000
(black). This property can be retrieved or set, even
* if there currently is no border, but the color is visible only if the text
* field has the border
property set to true
.
var bottomScrollV:Int
An integer(1-based index) that indicates the bottommost line that is
* currently visible in the specified text field. Think of the text field as
* a window onto a block of text. The scrollV
property is the
* 1-based index of the topmost visible line in the window.
*
*
All the text between the lines indicated by scrollV
and
* bottomScrollV
is currently visible in the text field.
var caretIndex:Int
The index of the insertion point(caret) position. If no insertion point * is displayed, the value is the position the insertion point would be if * you restored focus to the field(typically where the insertion point last * was, or 0 if the field has not had focus). * *
Selection span indexes are zero-based(for example, the first position * is 0, the second position is 1, and so on).
var condenseWhite:Bool
A Boolean value that specifies whether extra white space(spaces, line
* breaks, and so on) in a text field with HTML text is removed. The default
* value is If false
. The condenseWhite
property only
* affects text set with the htmlText
property, not the
* text
property. If you set text with the text
* property, condenseWhite
is ignored.
* condenseWhite
is set to true
, use standard
* HTML commands such as
and to place line
* breaks in the text field.
Set the condenseWhite
property before setting the
* htmlText
property.
var defaultTextFormat:TextFormat
Specifies the format applied to newly inserted text, such as text entered
* by a user or text inserted with the Note: When selecting characters to be replaced with
* replaceSelectedText()
* method.
* setSelection()
and replaceSelectedText()
, the
* defaultTextFormat
will be applied only if the text has been
* selected up to and including the last character. Here is an example: var mytxt:TextField new TextField();
* mytxt.text = "Flash Macintosh version"; var myfmt:TextFormat = new
* TextFormat(); myfmt.color = 0xFF0000; mytxt.defaultTextFormat = myfmt;
* mytxt.setSelection(6,15); // partial text selected - defaultTextFormat
* not applied mytxt.setSelection(6,23); // text selected to end -
* defaultTextFormat applied my_txt.replaceSelectedText("Windows version");
*
*
When you access the defaultTextFormat
property, the
* returned TextFormat object has all of its properties defined. No property
* is null
.
Note: You can't set this property if a style sheet is applied to * the text field.
* *Specifies whether the text field is a password text field. If the value of
* this property is true
, the text field is treated as a
* password text field and hides the input characters using asterisks instead
* of the actual characters. If false
, the text field is not
* treated as a password text field. When password mode is enabled, the Cut
* and Copy commands and their corresponding keyboard shortcuts will not
* function. This security mechanism prevents an unscrupulous user from using
* the shortcuts to discover a password on an unattended computer.
*
* @default false
var embedFonts:Bool
Specifies whether to render by using embedded font outlines. If
* false
, Flash Player renders the text field by using device
* fonts.
*
*
If you set the embedFonts
property to true
* for a text field, you must specify a font for that text by using the
* font
property of a TextFormat object applied to the text
* field. If the specified font is not embedded in the SWF file, the text is
* not displayed.
The type of grid fitting used for this text field. This property applies
* only if the The type of grid fitting used determines whether Flash Player forces
* strong horizontal and vertical lines to fit to a pixel or subpixel grid,
* or not at all.flash.text.AntiAliasType
property of the text
* field is set to flash.text.AntiAliasType.ADVANCED
.
*
For the flash.text.GridFitType
property, you can use the
* following string values:
Contains the HTML representation of the text field contents.
* Flash Player supports the following HTML tags:
Flash Player and AIR also support explicit character codes, such as * &(ASCII ampersand) and €(Unicode € symbol).
The maximum number of characters that the text field can contain, as
* entered by a user. A script can 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
* 0
, a user can enter an unlimited amount of text.
*
* @default 0
A Boolean value that indicates whether Flash Player automatically scrolls
* multiline text fields when the user clicks a text field and 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.
Indicates whether 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. In a field
* of type TextFieldType.INPUT
, the multiline
value
* determines whether the Enter
key creates a new line(a value
* of false
, and the Enter
key is ignored). If you
* paste text into a TextField
with a multiline
* value of false
, newlines are stripped out of the text.
*
* @default false
Defines the number of text lines in a multiline text field. If
* wordWrap
property is set to true
, the number of
* lines increases when text wraps.
Indicates the set of characters that a user can enter into the text field.
* If the value of the If the string begins with a caret(^) character, 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 a
* caret(^) character, no characters are initially accepted and succeeding
* characters in the string are included in the set of accepted
* characters. The following example allows only uppercase characters, spaces, and
* numbers to be entered into a text field: The following example includes all characters, but excludes lowercase
* letters: 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(^): The ^ can 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: You can use 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. You can specify a range by using the hyphen
* (-) character. Only user interaction is restricted; a script can put any
* text into the text field. mytxt.restrict = "A-Z 0-9";
*
* mytxt.restrict = "^a-z";
* my_txt.restrict = "\\-\\^";
* mytxt.restrict = "A-Z^Q";
*
* \u
escape sequence to construct
* restrict
strings. The following code includes only the
* characters from ASCII 32(space) to ASCII 126(tilde). mytxt.restrict = "\u0020-\u007E";
*
* @default null
The current horizontal scrolling position. If the The units of horizontal scrolling are pixels, whereas the units of
* vertical scrolling are lines. Horizontal scrolling is measured in pixels
* because most fonts you typically use are proportionally spaced; that is,
* the characters can have different widths. Flash Player performs vertical
* scrolling by line because users usually want to see a complete line of
* text rather than a partial line. Even if a line uses multiple fonts, the
* height of the line adjusts to fit the largest font in use.scrollH
* property is 0, the text is not horizontally scrolled. This property value
* is an integer that represents the horizontal position in pixels.
*
Note: The scrollH
property is zero-based, not
* 1-based like the scrollV
vertical scrolling property.
The vertical position of text in a text field. The scrollV
* property is useful for directing users to a specific paragraph in a long
* passage, or creating scrolling text fields.
*
*
The units of vertical scrolling are lines, whereas the units of * horizontal scrolling are pixels. If the first line displayed is the first * line in the text field, scrollV is set to 1(not 0). Horizontal scrolling * is measured in pixels because most fonts are proportionally spaced; that * is, the characters can have different widths. Flash performs vertical * scrolling by line because users usually want to see a complete line of * text rather than 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.
var selectable:Bool
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, 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, the user 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 with the Copy command. If
* selectable
is set to true
, the text in the text
* field can be selected with the mouse or keyboard, and the text can be
* copied with the Copy command. You can select text this way even if the
* text field is a dynamic text field instead of an input text field.
The zero-based character index value of the first character in the current
* selection. For example, the first character is 0, the second character is
* 1, and so on. If no text is selected, this property is the value of
* caretIndex
.
var selectionEndIndex:Int
The zero-based character index value of the last character in the current
* selection. For example, the first character is 0, the second character is
* 1, and so on. If no text is selected, this property is the value of
* caretIndex
.
The sharpness of the glyph edges in this text field. This property applies
* only if the flash.text.AntiAliasType
property of the text
* field is set to flash.text.AntiAliasType.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).
*
* @default 0
var styleSheet:StyleSheet
Attaches a style sheet to the text field. For information on creating
* style sheets, see the StyleSheet class and the ActionScript 3.0
* Developer's Guide.
* You can change the style sheet associated with a text field at any
* time. If you change the style sheet in use, the text field is redrawn with
* the new style sheet. You can set the style sheet 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.
Note: If the style sheet is removed, the contents of both
* TextField.text
and TextField.htmlText
change to
* incorporate the formatting previously applied by the style sheet. To
* preserve the original TextField.htmlText
contents without the
* formatting, save the value in a variable before removing the style
* sheet.
A string that is the current text in the text field. Lines are separated
* by the carriage return character('\r'
, ASCII 13). This
* property contains unformatted text in the text field, without HTML tags.
*
*
To get the text in HTML form, use the htmlText
* property.
The color of the text in a text field, in hexadecimal format. The
* hexadecimal color system uses six digits to represent color values. Each
* digit has 16 possible values or characters. The characters range from 0-9
* and then A-F. For example, black is 0x000000
; white is
* 0xFFFFFF
.
*
* @default 0(0x000000)
var textInteractionMode:TextInteractionMode
The interaction mode property, Default value is * TextInteractionMode.NORMAL. On mobile platforms, the normal mode implies * that the text can be scrolled but not selected. One can switch to the * selectable mode through the in-built context menu on the text field. On * Desktop, the normal mode implies that the text is in scrollable as well as * selection mode.
The thickness of the glyph edges in this text field. This property applies
* only when flash.text.AntiAliasType
is set to
* flash.text.AntiAliasType.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).
var type:TextFieldType
The type of the text field. Either one of the following TextFieldType
* constants: TextFieldType.DYNAMIC
, which specifies a dynamic
* text field, which a user cannot edit, or TextFieldType.INPUT
,
* which specifies an input text field, which a user can edit.
*
* @default dynamic
*
Specifies whether to copy and paste the text formatting along with the
* text. When set to true
, Flash Player copies and pastes
* formatting(such as alignment, bold, and italics) when you copy and paste
* between text fields. Both the origin and destination text fields for the
* copy and paste procedure must have useRichTextClipboard
set
* to true
. The default value is false
.
A Boolean value that indicates whether 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. The default value is false
.
Creates a new TextField instance. After you create the TextField instance,
* call the addChild()
or addChildAt()
method of
* the parent DisplayObjectContainer object to add the TextField instance to
* the display list.
*
*
The default size for a text field is 100 x 100 pixels.
function appendText(newText:String):Void
Appends the string specified by the newText
parameter to the
* end of the text of the text field. This method is more efficient than an
* addition assignment(+=
) on a text
property
* (such as someTextField.text += moreText
), particularly for a
* text field that contains a significant amount of content.
*
*
newText | The string to append to the existing text. |
function getCharBoundaries(charIndex:Int):Rectangle
Returns a rectangle that is the bounding box of the character. * *
charIndex | The zero-based index value for the character(for example, the first position is 0, the second position is 1, and so on). * |
returns | A rectangle with |
function getCharIndexAtPoint(x:Float, y:Float):Int
Returns the zero-based index value of the character at the point specified
* by the x
and y
parameters.
*
*
x | The x coordinate of the character. * |
y | The y coordinate of the character. * |
returns | The zero-based index value of the character(for example, the first position is 0, the second position is 1, and so on). Returns -1 if the point is not over any character. |
function getFirstCharInParagraph(charIndex:Int):Int
Given a character index, returns the index of the first character in the * same paragraph. * *
charIndex | The zero-based index value of the character(for example, the first character is 0, the second character is 1, and so on). * |
returns | The zero-based index value of the first character in the same paragraph. |
function getImageReference(id:String):DisplayObject
Returns a DisplayObject reference for the given id
, for an
* image or SWF file that has been added to an HTML-formatted text field by
* using an
tag. The
tag is in the
* following format:
*
*
<img src = 'filename.jpg' id =
* 'instanceName' >
*
* id | The |
returns | The display object corresponding to the image or SWF file with the
matching |
function getLineIndexAtPoint(x:Float, y:Float):Int
Returns the zero-based index value of the line at the point specified by
* the x
and y
parameters.
*
*
x | The x coordinate of the line. * |
y | The y coordinate of the line. * |
returns | The zero-based index value of the line(for example, the first line is 0, the second line is 1, and so on). Returns -1 if the point is not over any line. |
function getLineIndexOfChar(charIndex:Int):Int
Returns the zero-based index value of the line containing the character
* specified by the charIndex
parameter.
*
*
charIndex | The zero-based index value of the character(for example, the first character is 0, the second character is 1, and so on). * |
returns | The zero-based index value of the line. * |
function getLineLength(lineIndex:Int):Int
Returns the number of characters in a specific text line. * *
lineIndex | The line number for which you want the length. * |
returns | The number of characters in the line. * |
function getLineMetrics(lineIndex:Int):TextLineMetrics
Returns metrics information about a given text line. * *
lineIndex | The line number for which you want metrics information. * |
returns | A TextLineMetrics object. * |
function getLineOffset(lineIndex:Int):Int
Returns the character index of the first character in the line that the
* lineIndex
parameter specifies.
*
*
lineIndex | The zero-based index value of the line(for example, the first line is 0, the second line is 1, and so on). |
returns | The zero-based index value of the first character in the line. * |
function getLineText(lineIndex:Int):String
Returns the text of the line specified by the lineIndex
* parameter.
*
*
lineIndex | The zero-based index value of the line(for example, the first line is 0, the second line is 1, and so on). |
returns | The text string contained in the specified line. * |
function getParagraphLength(charIndex:Int):Int
Given a character index, returns the length of the paragraph containing
* the given character. The length is relative to the first character in the
* paragraph(as returned by getFirstCharInParagraph()
), not to
* the character index passed in.
*
*
charIndex | The zero-based index value of the character(for example, the first character is 0, the second character is 1, and so on). * |
returns | Returns the number of characters in the paragraph. * |
function getTextFormat(?beginIndex:Int, ?endIndex:Int):TextFormat
Returns a TextFormat object that contains formatting information for the
* range of text that the If you do not specify values for these parameters, this method is
* applied to all the text in the text field. beginIndex
and endIndex
* parameters specify. Only properties that are common to the entire text
* specified 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
.
*
The following table describes three possible usages:
* *returns | The TextFormat object that represents the formatting properties for the specified text. |
function replaceSelectedText(value:String):Void
Replaces the current selection with the contents of the You can use the value
* 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.
* replaceSelectedText()
method to insert and
* delete text without disrupting the character and paragraph formatting of
* the rest of the text.
Note: This method does not work if a style sheet is applied to * the text field.
* *value | The string to replace the currently selected text. * |
function replaceText(beginIndex:Int, endIndex:Int, newText:String):Void
Replaces the range of characters that the beginIndex
and
* endIndex
parameters specify with the contents of the
* newText
parameter. As designed, the text from
* beginIndex
to endIndex-1
is replaced.
*
*
Note: This method does not work if a style sheet is applied to * the text field.
* *beginIndex | The zero-based index value for the start position of the replacement range. |
endIndex | The zero-based index position of the first character * after the desired text span. * |
newText | The text to use to replace the specified range of * characters. * |
function setSelection(beginIndex:Int, endIndex:Int):Void
Sets as selected the text designated by the index values of the first and
* last characters, which are specified with the beginIndex
and
* endIndex
parameters. If the two parameter values are the
* same, this method sets the insertion point, as if you set the
* caretIndex
property.
*
*
beginIndex | The zero-based index value of the first character in the selection(for example, the first character is 0, the second character is 1, and so on). * |
endIndex | The zero-based index value of the last character in the * selection. |
function setTextFormat(format:TextFormat, ?beginIndex:Int, ?endIndex:Int):Void
Applies the text formatting that the Note: This method does not work if a style sheet is applied to
* the text field.format
parameter
* specifies to the specified text in a text field. The value of
* format
must be a TextFormat object that specifies the desired
* text formatting changes. Only the non-null properties of
* format
are applied to the text field. Any property of
* format
that is set to null
is not applied. By
* default, all of the properties of a newly created TextFormat object are
* set to null
.
*
The setTextFormat()
method changes the text formatting
* applied to a range of characters or to the entire body of text in a text
* field. To apply the properties of format to all text in the text field, do
* not specify values for beginIndex
and endIndex
.
* To apply the properties of the format to a range of text, specify values
* for the beginIndex
and the endIndex
parameters.
* You can use the length
property to determine the index
* values.
The two types of formatting information in a TextFormat object are * character level formatting and paragraph level formatting. Each character * in a text field can 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.
* *Any text inserted manually by the user, or replaced by the
* replaceSelectedText()
method, receives the default text field
* formatting for new text, and not the formatting specified for the text
* insertion point. To set the default formatting for new text, use
* defaultTextFormat
.
format | A TextFormat object that contains character and paragraph formatting information. |