The TextField class is used to create display objects for text display and input. 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. <ph outputclass="flashonly">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, use the TextField() constructor.

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

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 htmlText property.

@event change Dispatched after a control value is

							 modified, unlike the
							 `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.

							 **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
							 `textInput` events.

@event scroll Dispatched by a TextField object

							 _after_ the user scrolls.

@event textInput Flash Player dispatches the

							 `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

Constructor

new ()

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.

Variables

antiAliasType:AntiAliasType

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.

autoSize:TextFieldAutoSize

Controls automatic sizing and alignment of text fields. Acceptable values for the TextFieldAutoSize constants: TextFieldAutoSize.NONE(the default), TextFieldAutoSize.LEFT, TextFieldAutoSize.RIGHT, and TextFieldAutoSize.CENTER.

If 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.

Throws:

ArgumentError

The autoSize specified is not a member of openfl.text.TextFieldAutoSize.

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.

backgroundColor:Int

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.

border:Bool

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.

borderColor:Int

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.

read onlybottomScrollV: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.

read onlycaretIndex: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).

defaultTextFormat:TextFormat

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 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. If condenseWhite is set to true, use standard HTML commands such as <BR> and <P> to place line breaks in the text field.

Set the condenseWhite property before setting the htmlText property.

displayAsPassword:Bool

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.

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.

gridFitType:GridFitType

The type of grid fitting used for this text field. This property applies only if the openfl.text.AntiAliasType property of the text field is set to openfl.text.AntiAliasType.ADVANCED. 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.

For the openfl.text.GridFitType property, you can use the following string values:

String valueDescription
openfl.text.GridFitType.NONESpecifies no grid fitting. Horizontal and vertical lines in the glyphs are not forced to the pixel grid. This setting is recommended for animation or for large font sizes.
openfl.text.GridFitType.PIXELSpecifies 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 openfl.dispaly.AntiAliasType property of the text field must be set to openfl.text.AntiAliasType.ADVANCED. This setting generally provides the best legibility for left-aligned text.
openfl.text.GridFitType.SUBPIXELSpecifies that strong horizontal and vertical lines are fit to the subpixel grid on an LCD monitor. To use this setting, the openfl.text.AntiAliasType property of the text field must be set to openfl.text.AntiAliasType.ADVANCED. The openfl.text.GridFitType.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.

htmlText:UTF8String

Contains the HTML representation of the text field contents. Flash Player supports the following HTML tags:

TagDescription
Anchor tagThe <a> tag creates a hypertext link and supports the following attributes:
  • target: Specifies the name of the target window where you load the page. Options include _self, _blank, _parent, and _top. The _self option 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.
  • href: Specifies a URL or an ActionScript link event.The URL can be either absolute or relative to the location of the SWF file that is loading the page. An example of an absolute reference to a URL is http://www.adobe.com; an example of a relative reference is /index.html. Absolute URLs must be prefixed with http://; otherwise, Flash Player or AIR treats them as relative URLs. You can use the link event to cause the link to execute an ActionScript function in a SWF file instead of opening a URL. To specify a link event, use the event scheme instead of the http scheme in your href attribute. An example is href="event:myText" instead of href="http://myURL"; when the user clicks a hypertext link that contains the event scheme, the text field dispatches a link TextEvent with its text property set to "myText". You can then create an ActionScript function that executes whenever the link TextEvent is dispatched. You can also define a:link, a:hover, and a:active styles for anchor tags by using style sheets.
Bold tagThe <b> tag renders text as bold. A bold typeface must be available for the font used.
Break tagThe <br> tag creates a line break in the text field. Set the text field to be a multiline text field to use this tag.
Font tagThe <font> tag specifies a font or list of fonts to display the text.The font tag supports the following attributes:
  • color: Only hexadecimal color (#FFFFFF) values are supported.
  • face: Specifies the name of the font to use. As shown in the following example, you can specify a list of comma-delimited font names, in which case Flash Player selects the first available font. If the specified font is not installed on the local computer system or isn't embedded in the SWF file, Flash Player selects a substitute font.
  • size: Specifies the size of the font. You can use absolute pixel sizes, such as 16 or 18, or relative point sizes, such as +2 or -4.
Image tagThe <img> tag lets you embed external image files (JPEG, GIF, PNG), SWF files, and movie clips inside text fields. Text automatically flows around images you embed in text fields. You must set the text field to be multiline to wrap text around an image.
The <img> tag supports the following attributes:
  • src: Specifies the URL to an image or SWF file, or the linkage identifier for a movie clip symbol in the library. This attribute is required; all other attributes are optional. External files (JPEG, GIF, PNG, and SWF files) do not show until they are downloaded completely.
  • width: The width of the image, SWF file, or movie clip being inserted, in pixels.
  • height: The height of the image, SWF file, or movie clip being inserted, in pixels.
  • align: Specifies the horizontal alignment of the embedded image within the text field. Valid values are left and right. The default value is left.
  • hspace: Specifies the amount of horizontal space that surrounds the image where no text appears. The default value is 8.
  • vspace: Specifies the amount of vertical space that surrounds the image where no text appears. The default value is 8.
  • id: Specifies the name for the movie clip instance (created by Flash Player) that contains the embedded image file, SWF file, or movie clip. This approach is used to control the embedded content with ActionScript.
  • checkPolicyFile: Specifies that Flash Player checks for a URL policy file on the server associated with the image domain. If a policy file exists, SWF files in the domains listed in the file can access the data of the loaded image, for example, by calling the BitmapData.draw() method with this image as the source parameter. For more information related to security, see the Flash Player Developer Center Topic: Security.
Flash displays media embedded in a text field at full size. To specify the dimensions of the media you are embedding, use the <img> tag height and width attributes.
In general, an image embedded in a text field appears on the line following the <img> tag. However, when the <img> tag is the first character in the text field, the image appears on the first line of the text field.
For AIR content in the application security sandbox, AIR ignores img tags in HTML content in ActionScript TextField objects. This is to prevent possible phishing attacks.
Italic tagThe <i> tag displays the tagged text in italics. An italic typeface must be available for the font used.
List item tagThe <li> tag places a bullet in front of the text that it encloses.
Note: Because Flash Player and AIR do not recognize ordered and unordered list tags (<ol> and <ul>, they do not modify how your list is rendered. All lists are unordered and all list items use bullets.
Paragraph tagThe <p> tag creates a new paragraph. The text field must be set to be a multiline text field to use this tag. The <p> tag supports the following attributes:
  • align: Specifies alignment of text within the paragraph; valid values are left, right, justify, and center.
  • class: Specifies a CSS style class defined by a openfl.text.StyleSheet object.
Span tagThe <span> tag is available only for use with CSS text styles. It supports the following attribute:
  • class: Specifies a CSS style class defined by a openfl.text.StyleSheet object.
Text format tagThe <textformat> tag lets you use a subset of paragraph formatting properties of the TextFormat class within text fields, including line leading, indentation, margins, and tab stops. You can combine <textformat> tags with the built-in HTML tags.
The <textformat> tag has the following attributes:
  • blockindent: Specifies the block indentation in points; corresponds to TextFormat.blockIndent.
  • indent: Specifies the indentation from the left margin to the first character in the paragraph; corresponds to TextFormat.indent. Both positive and negative numbers are acceptable.
  • leading: Specifies the amount of leading (vertical space) between lines; corresponds to TextFormat.leading. Both positive and negative numbers are acceptable.
  • leftmargin: Specifies the left margin of the paragraph, in points; corresponds to TextFormat.leftMargin.
  • rightmargin: Specifies the right margin of the paragraph, in points; corresponds to TextFormat.rightMargin.
  • tabstops: Specifies custom tab stops as an array of non-negative integers; corresponds to TextFormat.tabStops.
  • Underline tagThe <u> tag underlines the tagged text.

    Flash Player and AIR support the following HTML entities:

    EntityDescription
    &lt;< (less than)
    &gt;> (greater than)
    &amp;& (ampersand)
    &quot;" (double quotes)
    &apos;' (apostrophe, single quote)

    Flash Player and AIR also support explicit character codes, such as & (ASCII ampersand) and € (Unicode € symbol).

    read onlylength:Int

    The number of characters in a text field. A character such as tab (\t) counts as one character.

    maxChars:Int

    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.

    read onlymaxScrollH:Int

    The maximum value of scrollH.

    read onlymaxScrollV:Int

    The maximum value of scrollV.

    multiline:Bool

    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.

    read onlynumLines:Int

    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.

    restrict:UTF8String

    Indicates the set of characters that a user can 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. 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. This property does not synchronize with the Embed font options in the Property inspector.

    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: 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 ^ 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: 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";

    scrollH:Int

    The current horizontal scrolling position. If the scrollH property is 0, the text is not horizontally scrolled. This property value is an integer that represents the horizontal position in pixels.

    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.

    Note: The scrollH property is zero-based, not 1-based like the scrollV vertical scrolling property.

    scrollV:Int

    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.

    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.

    read onlyselectionBeginIndex:Int

    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.

    read onlyselectionEndIndex: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.

    sharpness:Float

    The sharpness of the glyph edges in this text field. This property applies only if the openfl.text.AntiAliasType property of the text field is set to openfl.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).

    text:UTF8String

    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.

    textColor:Int

    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.

    read onlytextHeight:Float

    The height of the text in pixels.

    read onlytextWidth:Float

    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.

    type:TextFieldType

    The thickness of the glyph edges in this text field. This property applies only when openfl.text.AntiAliasType is set to openfl.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).

    wordWrap:Bool

    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.

    Methods

    appendText (text: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.

    Parameters:

    newText

    The string to append to the existing text.

    getCharBoundaries (charIndex:Int):Rectangle

    Returns a rectangle that is the bounding box of the character.

    Parameters:

    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 x and y minimum and maximum values defining the bounding box of the character.

    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.

    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.

    getFirstCharInParagraph (charIndex:Int):Int

    Given a character index, returns the index of the first character in the same paragraph.

    Parameters:

    charIndex

    The zero-based index value of the character (for example, the first character is 0, the second character is 1, and so on).

    Throws:

    RangeError

    The character index specified is out of range.

    Returns:

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

    getLineIndexAtPoint (x:Float, y:Float):Int

    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 <img> tag. The <img> tag is in the following format:

     <img src = 'filename.jpg' id =
    'instanceName' >

    Parameters:

    id

    The id to match (in the id attribute of the <img> tag).

    Returns:

    The display object corresponding to the image or SWF file with the matching id attribute in the <img> tag of the text field. For media loaded from an external source, this object is a Loader object, and, once loaded, the media object is a child of that Loader object. For media embedded in the SWF file, it is the loaded object. If no <img> tag with the matching id exists, the method returns null.

    getLineIndexOfChar (charIndex:Int):Int

    Returns the zero-based index value of the line containing the character specified by the charIndex parameter.

    Parameters:

    charIndex

    The zero-based index value of the character (for example, the first character is 0, the second character is 1, and so on).

    Throws:

    RangeError

    The character index specified is out of range.

    Returns:

    The zero-based index value of the line.

    getLineLength (lineIndex:Int):Int

    Returns the number of characters in a specific text line.

    Parameters:

    lineIndex

    The line number for which you want the length.

    Throws:

    RangeError

    The line number specified is out of range.

    Returns:

    The number of characters in the line.

    getLineMetrics (lineIndex:Int):TextLineMetrics

    Returns metrics information about a given text line.

    Parameters:

    lineIndex

    The line number for which you want metrics information.

    Throws:

    RangeError

    The line number specified is out of range.

    Returns:

    A TextLineMetrics object.

    getLineOffset (lineIndex:Int):Int

    Returns the character index of the first character in the line that the lineIndex parameter specifies.

    Parameters:

    lineIndex

    The zero-based index value of the line(for example, the first line is 0, the second line is 1, and so on).

    Throws:

    RangeError

    The line number specified is out of range.

    Returns:

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

    getLineText (lineIndex:Int):String

    Returns the text of the line specified by the lineIndex parameter.

    Parameters:

    lineIndex

    The zero-based index value of the line(for example, the first line is 0, the second line is 1, and so on).

    Throws:

    RangeError

    The line number specified is out of range.

    Returns:

    The text string contained in the specified line.

    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.

    Parameters:

    charIndex

    The zero-based index value of the character (for example, the first character is 0, the second character is 1, and so on).

    Throws:

    RangeError

    The character index specified is out of range.

    Returns:

    Returns the number of characters in the paragraph.

    getTextFormat (beginIndex:Int = -1, endIndex:Int = -1):TextFormat

    Returns a TextFormat object that contains formatting information for the range of text that the 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. If you do not specify values for these parameters, this method is applied to all the text in the text field.

    The following table describes three possible usages:

    UsageDescription
    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 format of the character 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-1. 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.

    Throws:

    RangeError

    The beginIndex or endIndex specified is out of range.

    Returns:

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

    replaceSelectedText (value:String):Void

    Returns true if an embedded font is available with the specified fontName and fontStyle where Font.fontType is openfl.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 openfl.text.engine classes. The two types are distinguished by the fontType property of the Font class, as returned by the enumerateFonts() function. TextField cannot use a font of type EMBEDDED_CFF. If embedFonts is set to true and the only font available at run time with the specified name and style is of type EMBEDDED_CFF, Flash Player fails to render the text, as if no embedded font were available with the specified name and style.

    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.

    Parameters:

    fontName

    The name of the embedded font to check.

    fontStyle

    Specifies the font style to check. Use openfl.text.FontStyle

    Throws:

    ArgumentError

    The fontStyle specified is not a member of openfl.text.FontStyle.

    Returns:

    true if a compatible embedded font is available, otherwise false.

    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.

    Parameters:

    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.

    Throws:

    Error

    This method cannot be used on a text field with a style sheet.

    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.

    Parameters:

    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.

    setTextFormat (format:TextFormat, beginIndex:Int = 0, endIndex:Int = 0):Void

    Applies the text formatting that the 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.

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

    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.

    Parameters:

    format

    A TextFormat object that contains character and paragraph formatting information.

    Throws:

    Error

    This method cannot be used on a text field with a style sheet.

    RangeError

    The beginIndex or endIndex specified is out of range.

    Inherited Variables

    Defined by InteractiveObject

    doubleClickEnabled:Bool

    Specifies whether the object receives doubleClick events. The default value is false, which means that by default an InteractiveObject instance does not receive doubleClick events. If the doubleClickEnabled property is set to true, the instance receives doubleClick events within its bounds. The mouseEnabled property of the InteractiveObject instance must also be set to true for the object to receive doubleClick events.

    No event is dispatched by setting this property. You must use the addEventListener() method to add an event listener for the doubleClick event.

    focusRect:Null<Bool>

    Specifies whether this object displays a focus rectangle. It can take one of three values: true, false, or null. Values of true and false work as expected, specifying whether or not the focus rectangle appears. A value of null indicates that this object obeys the stageFocusRect property of the Stage.

    mouseEnabled:Bool

    Specifies whether this object receives mouse, or other user input, messages. The default value is true, which means that by default any InteractiveObject instance that is on the display list receives mouse events or other user input events. If mouseEnabled is set to false, the instance does not receive any mouse events(or other user input events like keyboard events). Any children of this instance on the display list are not affected. To change the mouseEnabled behavior for all children of an object on the display list, use openfl.display.DisplayObjectContainer.mouseChildren.

    No event is dispatched by setting this property. You must use the addEventListener() method to create interactive functionality.

    needsSoftKeyboard:Bool

    Specifies whether a virtual keyboard(an on-screen, software keyboard) should display when this InteractiveObject instance receives focus.

    By default, the value is false and focusing an InteractiveObject instance does not raise a soft keyboard. If the needsSoftKeyboard property is set to true, the runtime raises a soft keyboard when the InteractiveObject instance is ready to accept user input. An InteractiveObject instance is ready to accept user input after a programmatic call to set the Stage focus property or a user interaction, such as a "tap." If the client system has a hardware keyboard available or does not support virtual keyboards, then the soft keyboard is not raised.

    The InteractiveObject instance dispatches softKeyboardActivating, softKeyboardActivate, and softKeyboardDeactivate events when the soft keyboard raises and lowers.

    Note: This property is not supported in AIR applications on iOS.

    softKeyboardInputAreaOfInterest:Rectangle

    Defines the area that should remain on-screen when a soft keyboard is displayed. If the needsSoftKeyboard property of this InteractiveObject is true, then the runtime adjusts the display as needed to keep the object in view while the user types. Ordinarily, the runtime uses the object bounds obtained from the DisplayObject.getBounds() method. You can specify a different area using this softKeyboardInputAreaOfInterest property.

    Specify the softKeyboardInputAreaOfInterest in stage coordinates.

    Note: On Android, the softKeyboardInputAreaOfInterest is not respected in landscape orientations.

    tabEnabled:Bool

    Specifies whether this object is in the tab order. If this object is in the tab order, the value is true; otherwise, the value is false. By default, the value is false, except for the following: For a SimpleButton object, the value is true. For a TextField object with type = "input", the value is true. * For a Sprite object or MovieClip object with buttonMode = true, the value is true.

    tabIndex:Int

    Specifies the tab ordering of objects in a SWF file. The tabIndex property is -1 by default, meaning no tab index is set for the object.

    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 includes only objects that have tabIndex properties.

    The tabIndex property can be a non-negative 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. Do not use the same tabIndex value for multiple objects.

    The custom tab ordering that the tabIndex property defines 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.

    Note: To set the tab order for TLFTextField instances, cast the display object child of the TLFTextField as an InteractiveObject, then set the tabIndex property. For example:

    InteractiveObject(tlfInstance.getChildAt(1)).tabIndex = 3; 
    To reverse the tab order from the default setting for three instances of a TLFTextField object (tlfInstance1, tlfInstance2 and tlfInstance3), use:
    InteractiveObject(tlfInstance1.getChildAt(1)).tabIndex = 3;
    InteractiveObject(tlfInstance2.getChildAt(1)).tabIndex = 2;
    InteractiveObject(tlfInstance3.getChildAt(1)).tabIndex = 1; 

    Defined by DisplayObject

    alpha:Float

    Indicates the alpha transparency value of the object specified. Valid values are 0(fully transparent) to 1(fully opaque). The default value is 1. Display objects with alpha set to 0 are active, even though they are invisible.

    blendMode:BlendMode

    A value from the BlendMode class that specifies which blend mode to use. A bitmap can be drawn internally in two ways. If you have a blend mode enabled or an external clipping mask, the bitmap is drawn by adding a bitmap-filled square shape to the vector render. If you attempt to set this property to an invalid value, Flash runtimes set the value to BlendMode.NORMAL.

    The blendMode property affects each pixel of the display object. Each pixel is composed of three constituent colors(red, green, and blue), and each constituent color has a value between 0x00 and 0xFF. Flash Player or Adobe AIR compares each constituent color of one pixel in the movie clip with the corresponding color of the pixel in the background. For example, if blendMode is set to BlendMode.LIGHTEN, Flash Player or Adobe AIR compares the red value of the display object with the red value of the background, and uses the lighter of the two as the value for the red component of the displayed color.

    The following table describes the blendMode settings. The BlendMode class defines string values you can use. The illustrations in the table show blendMode values applied to a circular display object(2) superimposed on another display object(1).

    cacheAsBitmap:Bool

    All vector data for a display object that has a cached bitmap is drawn to the bitmap instead of the main display. If cacheAsBitmapMatrix is null or unsupported, the bitmap is then copied to the main display as unstretched, unrotated pixels snapped to the nearest pixel boundaries. Pixels are mapped 1 to 1 with the parent object. If the bounds of the bitmap change, the bitmap is recreated instead of being stretched.

    If cacheAsBitmapMatrix is non-null and supported, the object is drawn to the off-screen bitmap using that matrix and the stretched and/or rotated results of that rendering are used to draw the object to the main display.

    No internal bitmap is created unless the cacheAsBitmap property is set to true.

    After you set the cacheAsBitmap property to true, the rendering does not change, however the display object performs pixel snapping automatically. The animation speed can be significantly faster depending on the complexity of the vector content.

    The cacheAsBitmap property is automatically set to true whenever you apply a filter to a display object(when its filter array is not empty), and if a display object has a filter applied to it, cacheAsBitmap is reported as true for that display object, even if you set the property to false. If you clear all filters for a display object, the cacheAsBitmap setting changes to what it was last set to.

    A display object does not use a bitmap even if the cacheAsBitmap property is set to true and instead renders from vector data in the following cases:

    • The bitmap is too large. In AIR 1.5 and Flash Player 10, the maximum size for a bitmap image is 8,191 pixels in width or height, and the total number of pixels cannot exceed 16,777,215 pixels.(So, if a bitmap image is 8,191 pixels wide, it can only be 2,048 pixels high.) In Flash Player 9 and earlier, the limitation is is 2880 pixels in height and 2,880 pixels in width.
    • The bitmap fails to allocate(out of memory error).

    The cacheAsBitmap property is best used with movie clips that have mostly static content and that do not scale and rotate frequently. With such movie clips, cacheAsBitmap can lead to performance increases when the movie clip is translated(when its x and y position is changed).

    filters:Array<BitmapFilter>

    An indexed array that contains each filter object currently associated with the display object. The openfl.filters package contains several classes that define specific filters you can use.

    Filters can be applied in Flash Professional at design time, or at run time by using ActionScript code. To apply a filter by using ActionScript, you must make a temporary copy of the entire filters array, modify the temporary array, then assign the value of the temporary array back to the filters array. You cannot directly add a new filter object to the filters array.

    To add a filter by using ActionScript, perform the following steps (assume that the target display object is named myDisplayObject):

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

    If the filters array is undefined, you do not need to use a temporary array. Instead, you can directly assign an array literal that contains one or more filter objects that you create. The first example in the Examples section adds a drop shadow filter by using code that handles both defined and undefined filters arrays.

    To modify an existing filter object, you must use the technique of modifying a copy of the filters array:

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

    At load time, if a display object has an associated filter, it is marked to cache itself as a transparent bitmap. From this point forward, as long as the display object has a valid filter list, the player caches the display object as a bitmap. This source bitmap is used as a source image for the filter effects. Each display object usually has two bitmaps: one with the original unfiltered source display object and another for the final image after filtering. The final image is used when rendering. As long as the display object does not change, the final image does not need updating.

    The openfl.filters package includes classes for filters. For example, to create a DropShadow filter, you would write:

    Throws:

    ArgumentError

    When filters includes a ShaderFilter and the shader output type is not compatible with this operation(the shader must specify a pixel4 output).

    ArgumentError

    When filters includes a ShaderFilter and the shader doesn't specify any image input or the first input is not an image4 input.

    ArgumentError

    When filters includes a ShaderFilter and the shader specifies an image input that isn't provided.

    ArgumentError

    When filters includes a ShaderFilter, a ByteArray or Vector. instance as a shader input, and the width and height properties aren't specified for the ShaderInput object, or the specified values don't match the amount of data in the input data. See the ShaderInput.input property for more information.

    height:Float

    Indicates the height of the display object, in pixels. The height is calculated based on the bounds of the content of the display object. When you set the height property, the scaleY property is adjusted accordingly, as shown in the following code:

    Except for TextField and Video objects, a display object with no content(such as an empty sprite) has a height of 0, even if you try to set height to a different value.

    read onlyloaderInfo:LoaderInfo

    Returns a LoaderInfo object containing information about loading the file to which this display object belongs. The loaderInfo property is defined only for the root display object of a SWF file or for a loaded Bitmap(not for a Bitmap that is drawn with ActionScript). To find the loaderInfo object associated with the SWF file that contains a display object named myDisplayObject, use myDisplayObject.root.loaderInfo.

    A large SWF file can monitor its download by calling this.root.loaderInfo.addEventListener(Event.COMPLETE, func).

    mask:DisplayObject

    The calling display object is masked by the specified mask object. To ensure that masking works when the Stage is scaled, the mask display object must be in an active part of the display list. The mask object itself is not drawn. Set mask to null to remove the mask.

    To be able to scale a mask object, it must be on the display list. To be able to drag a mask Sprite object(by calling its startDrag() method), it must be on the display list. To call the startDrag() method for a mask sprite based on a mouseDown event being dispatched by the sprite, set the sprite's buttonMode property to true.

    When display objects are cached by setting the cacheAsBitmap property to true an the cacheAsBitmapMatrix property to a Matrix object, both the mask and the display object being masked must be part of the same cached bitmap. Thus, if the display object is cached, then the mask must be a child of the display object. If an ancestor of the display object on the display list is cached, then the mask must be a child of that ancestor or one of its descendents. If more than one ancestor of the masked object is cached, then the mask must be a descendent of the cached container closest to the masked object in the display list.

    Note: A single mask object cannot be used to mask more than one calling display object. When the mask is assigned to a second display object, it is removed as the mask of the first object, and that object's mask property becomes null.

    read onlymouseX:Float

    Indicates the x coordinate of the mouse or user input device position, in pixels.

    Note: For a DisplayObject that has been rotated, the returned x coordinate will reflect the non-rotated object.

    read onlymouseY:Float

    Indicates the y coordinate of the mouse or user input device position, in pixels.

    Note: For a DisplayObject that has been rotated, the returned y coordinate will reflect the non-rotated object.

    name:String

    Indicates the instance name of the DisplayObject. The object can be identified in the child list of its parent display object container by calling the getChildByName() method of the display object container.

    Throws:

    IllegalOperationError

    If you are attempting to set this property on an object that was placed on the timeline in the Flash authoring tool.

    opaqueBackground:Null<Int>

    Specifies whether the display object is opaque with a certain background color. A transparent bitmap contains alpha channel data and is drawn transparently. An opaque bitmap has no alpha channel(and renders faster than a transparent bitmap). If the bitmap is opaque, you specify its own background color to use.

    If set to a number value, the surface is opaque(not transparent) with the RGB background color that the number specifies. If set to null(the default value), the display object has a transparent background.

    The opaqueBackground property is intended mainly for use with the cacheAsBitmap property, for rendering optimization. For display objects in which the cacheAsBitmap property is set to true, setting opaqueBackground can improve rendering performance.

    The opaque background region is not matched when calling the hitTestPoint() method with the shapeFlag parameter set to true.

    The opaque background region does not respond to mouse events.

    read onlyparent:DisplayObjectContainer

    Indicates the DisplayObjectContainer object that contains this display object. Use the parent property to specify a relative path to display objects that are above the current display object in the display list hierarchy.

    You can use parent to move up multiple levels in the display list as in the following:

    Throws:

    SecurityError

    The parent display object belongs to a security sandbox to which you do not have access. You can avoid this situation by having the parent movie call the Security.allowDomain() method.

    read onlyroot:DisplayObject

    For a display object in a loaded SWF file, the root property is the top-most display object in the portion of the display list's tree structure represented by that SWF file. For a Bitmap object representing a loaded image file, the root property is the Bitmap object itself. For the instance of the main class of the first SWF file loaded, the root property is the display object itself. The root property of the Stage object is the Stage object itself. The root property is set to null for any display object that has not been added to the display list, unless it has been added to a display object container that is off the display list but that is a child of the top-most display object in a loaded SWF file.

    For example, if you create a new Sprite object by calling the Sprite() constructor method, its root property is null until you add it to the display list(or to a display object container that is off the display list but that is a child of the top-most display object in a SWF file).

    For a loaded SWF file, even though the Loader object used to load the file may not be on the display list, the top-most display object in the SWF file has its root property set to itself. The Loader object does not have its root property set until it is added as a child of a display object for which the root property is set.

    rotation:Float

    Indicates the rotation of the DisplayObject instance, 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_video.rotation = 450 is the same as my_video.rotation = 90.

    scale9Grid:Rectangle

    The current scaling grid that is in effect. If set to null, the entire display object is scaled normally when any scale transformation is applied.

    When you define the scale9Grid property, the display object is divided into a grid with nine regions based on the scale9Grid rectangle, which defines the center region of the grid. The eight other regions of the grid are the following areas:

    • The upper-left corner outside of the rectangle
    • The area above the rectangle
    • The upper-right corner outside of the rectangle
    • The area to the left of the rectangle
    • The area to the right of the rectangle
    • The lower-left corner outside of the rectangle
    • The area below the rectangle
    • The lower-right corner outside of the rectangle

    You can think of the eight regions outside of the center(defined by the rectangle) as being like a picture frame that has special rules applied to it when scaled.

    When the scale9Grid property is set and a display object is scaled, all text and gradients are scaled normally; however, for other types of objects the following rules apply:

    • Content in the center region is scaled normally.
    • Content in the corners is not scaled.
    • Content in the top and bottom regions is scaled horizontally only.
    • Content in the left and right regions is scaled vertically only.
    • All fills(including bitmaps, video, and gradients) are stretched to fit their shapes.

    If a display object is rotated, all subsequent scaling is normal(and the scale9Grid property is ignored).

    For example, consider the following display object and a rectangle that is applied as the display object's scale9Grid:

    A common use for setting scale9Grid is to set up a display object to be used as a component, in which edge regions retain the same width when the component is scaled.

    Throws:

    ArgumentError

    If you pass an invalid argument to the method.

    scaleX:Float

    Indicates the horizontal scale(percentage) of the object as applied from the registration point. The default registration point is(0,0). 1.0 equals 100% scale.

    Scaling the local coordinate system changes the x and y property values, which are defined in whole pixels.

    scaleY:Float

    Indicates the vertical scale(percentage) of an object as applied from the registration point of the object. The default registration point is(0,0). 1.0 is 100% scale.

    Scaling the local coordinate system changes the x and y property values, which are defined in whole pixels.

    scrollRect:Rectangle

    The scroll rectangle bounds of the display object. The display object is cropped to the size defined by the rectangle, and it scrolls within the rectangle when you change the x and y properties of the scrollRect object.

    The properties of the scrollRect Rectangle object use the display object's coordinate space and are scaled just like the overall display object. The corner bounds of the cropped window on the scrolling display object are the origin of the display object(0,0) and the point defined by the width and height of the rectangle. They are not centered around the origin, but use the origin to define the upper-left corner of the area. A scrolled display object always scrolls in whole pixel increments.

    You can scroll an object left and right by setting the x property of the scrollRect Rectangle object. You can scroll an object up and down by setting the y property of the scrollRect Rectangle object. If the display object is rotated 90° and you scroll it left and right, the display object actually scrolls up and down.

    read onlystage:Stage

    The Stage of the display object. A Flash runtime application has only one Stage object. For example, you can create and load multiple display objects into the display list, and the stage property of each display object refers to the same Stage object(even if the display object belongs to a loaded SWF file).

    If a display object is not added to the display list, its stage property is set to null.

    transform:Transform

    An object with properties pertaining to a display object's matrix, color transform, and pixel bounds. The specific properties - matrix, colorTransform, and three read-only properties (concatenatedMatrix, concatenatedColorTransform, and pixelBounds) - are described in the entry for the Transform class.

    Each of the transform object's properties is itself an object. This concept is important because the only way to set new values for the matrix or colorTransform objects is to create a new object and copy that object into the transform.matrix or transform.colorTransform property.

    For example, to increase the tx value of a display object's matrix, you must make a copy of the entire matrix object, then copy the new object into the matrix property of the transform object: var myMatrix:Matrix = myDisplayObject.transform.matrix; myMatrix.tx += 10; myDisplayObject.transform.matrix = myMatrix;

    You cannot directly set the tx property. The following code has no effect on myDisplayObject: myDisplayObject.transform.matrix.tx += 10;

    You can also copy an entire transform object and assign it to another display object's transform property. For example, the following code copies the entire transform object from myOldDisplayObj to myNewDisplayObj: myNewDisplayObj.transform = myOldDisplayObj.transform;

    The resulting display object, myNewDisplayObj, now has the same values for its matrix, color transform, and pixel bounds as the old display object, myOldDisplayObj.

    Note that AIR for TV devices use hardware acceleration, if it is available, for color transforms.

    visible:Bool

    Whether or not the display object is visible. Display objects that are not visible are disabled. For example, if visible=false for an InteractiveObject instance, it cannot be clicked.

    width:Float

    Indicates the width of the display object, in pixels. The width is calculated based on the bounds of the content of the display object. When you set the width property, the scaleX property is adjusted accordingly, as shown in the following code:

    Except for TextField and Video objects, a display object with no content(such as an empty sprite) has a width of 0, even if you try to set width to a different value.

    x:Float

    Indicates the x coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer. If the object is inside a DisplayObjectContainer that has transformations, it is in the local coordinate system of the enclosing DisplayObjectContainer. Thus, for a DisplayObjectContainer rotated 90° counterclockwise, the DisplayObjectContainer's children inherit a coordinate system that is rotated 90° counterclockwise. The object's coordinates refer to the registration point position.

    y:Float

    Indicates the y coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer. If the object is inside a DisplayObjectContainer that has transformations, it is in the local coordinate system of the enclosing DisplayObjectContainer. Thus, for a DisplayObjectContainer rotated 90° counterclockwise, the DisplayObjectContainer's children inherit a coordinate system that is rotated 90° counterclockwise. The object's coordinates refer to the registration point position.

    Inherited Methods

    Defined by InteractiveObject

    requestSoftKeyboard ():Bool

    Raises a virtual keyboard.

    Calling this method focuses the InteractiveObject instance and raises the soft keyboard, if necessary. The needsSoftKeyboard must also be true. A keyboard is not raised if a hardware keyboard is available, or if the client system does not support virtual keyboards.

    Note: This method is not supported in AIR applications on iOS.

    Returns:

    A value of true means that the soft keyboard request was granted; false means that the soft keyboard was not raised.

    Defined by DisplayObject

    getBounds (targetCoordinateSpace:DisplayObject):Rectangle

    Returns a rectangle that defines the area of the display object relative to the coordinate system of the targetCoordinateSpace object. Consider the following code, which shows how the rectangle returned can vary depending on the targetCoordinateSpace parameter that you pass to the method:

    Note: Use the localToGlobal() and globalToLocal() methods to convert the display object's local coordinates to display coordinates, or display coordinates to local coordinates, respectively.

    The getBounds() method is similar to the getRect() method; however, the Rectangle returned by the getBounds() method includes any strokes on shapes, whereas the Rectangle returned by the getRect() method does not. For an example, see the description of the getRect() method.

    Parameters:

    targetCoordinateSpace

    The display object that defines the coordinate system to use.

    Returns:

    The rectangle that defines the area of the display object relative to the targetCoordinateSpace object's coordinate system.

    getRect (targetCoordinateSpace:DisplayObject):Rectangle

    Returns a rectangle that defines the boundary of the display object, based on the coordinate system defined by the targetCoordinateSpace parameter, excluding any strokes on shapes. The values that the getRect() method returns are the same or smaller than those returned by the getBounds() method.

    Note: Use localToGlobal() and globalToLocal() methods to convert the display object's local coordinates to Stage coordinates, or Stage coordinates to local coordinates, respectively.

    Parameters:

    targetCoordinateSpace

    The display object that defines the coordinate system to use.

    Returns:

    The rectangle that defines the area of the display object relative to the targetCoordinateSpace object's coordinate system.

    globalToLocal (pos:Point):Point

    Converts the point object from the Stage(global) coordinates to the display object's(local) coordinates.

    To use this method, first create an instance of the Point class. The x and y values that you assign represent global coordinates because they relate to the origin(0,0) of the main display area. Then pass the Point instance as the parameter to the globalToLocal() method. The method returns a new Point object with x and y values that relate to the origin of the display object instead of the origin of the Stage.

    Parameters:

    point

    An object created with the Point class. The Point object specifies the x and y coordinates as properties.

    Returns:

    A Point object with coordinates relative to the display object.

    hitTestObject (obj:DisplayObject):Bool

    Evaluates the bounding box of the display object to see if it overlaps or intersects with the bounding box of the obj display object.

    Parameters:

    obj

    The display object to test against.

    Returns:

    true if the bounding boxes of the display objects intersect; false if not.

    hitTestPoint (x:Float, y:Float, shapeFlag:Bool = false):Bool

    Evaluates the display object to see if it overlaps or intersects with the point specified by the x and y parameters. The x and y parameters specify a point in the coordinate space of the Stage, not the display object container that contains the display object(unless that display object container is the Stage).

    Parameters:

    x

    The x coordinate to test against this object.

    y

    The y coordinate to test against this object.

    shapeFlag

    Whether to check against the actual pixels of the object (true) or the bounding box (false).

    Returns:

    true if the display object overlaps or intersects with the specified point; false otherwise.

    invalidate ():Void

    Calling the invalidate() method signals to have the current object redrawn the next time the object is eligible to be rendered.

    localToGlobal (point:Point):Point

    Converts the point object from the display object's(local) coordinates to the Stage(global) coordinates.

    This method allows you to convert any given x and y coordinates from values that are relative to the origin(0,0) of a specific display object(local coordinates) to values that are relative to the origin of the Stage(global coordinates).

    To use this method, first create an instance of the Point class. The x and y values that you assign represent local coordinates because they relate to the origin of the display object.

    You then pass the Point instance that you created as the parameter to the localToGlobal() method. The method returns a new Point object with x and y values that relate to the origin of the Stage instead of the origin of the display object.

    Parameters:

    point

    The name or identifier of a point created with the Point class, specifying the x and y coordinates as properties.

    Returns:

    A Point object with coordinates relative to the Stage.

    Defined by EventDispatcher

    hasEventListener (type:String):Bool

    Checks whether the EventDispatcher object has any listeners registered for a specific type of event. This allows you to determine where an EventDispatcher object has altered handling of an event type in the event flow hierarchy. To determine whether a specific event type actually triggers an event listener, use willTrigger().

    The difference between hasEventListener() and willTrigger() is that hasEventListener() examines only the object to which it belongs, whereas willTrigger() examines the entire event flow for the event specified by the type parameter.

    When hasEventListener() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

    Parameters:

    type

    The type of event.

    Returns:

    A value of true if a listener of the specified type is registered; false otherwise.

    toString ():String

    willTrigger (type:String):Bool

    Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. This method returns true if an event listener is triggered during any phase of the event flow when an event of the specified type is dispatched to this EventDispatcher object or any of its descendants.

    The difference between the hasEventListener() and the willTrigger() methods is that hasEventListener() examines only the object to which it belongs, whereas the willTrigger() method examines the entire event flow for the event specified by the type parameter.

    When willTrigger() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

    Parameters:

    type

    The type of event.

    Returns:

    A value of true if a listener of the specified type will be triggered; false otherwise.