ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
TextEvent

Package | flash.events
Class | public class TextEvent
Inheritance | TextEvent Event Object
Subclasses | DataEvent, ErrorEvent, IMEEvent

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Flash® Player dispatches TextEvent objects when a user enters text in a text field or clicks a hyperlink in an HTML-enabled text field. There are two types of text events: `TextEvent.LINK` and `TextEvent.TEXT_INPUT`.

View the examples

See also

flash.text.TextField

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | bubbles : Boolean [read-only] Indicates whether an event is a bubbling event. | Event
|  | cancelable : Boolean [read-only] Indicates whether the behavior associated with the event can be prevented. | Event
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | currentTarget : Object [read-only] The object that is actively processing the Event object with an event listener. | Event
|  | eventPhase : uint [read-only] The current phase in the event flow. | Event
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object
|  | target : Object [read-only] The event target. | Event
|  | text : String For a textInput event, the character or sequence of characters entered by the user. | TextEvent
|  | type : String [read-only] The type of event. | Event

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | TextEvent(type:String, bubbles:Boolean = false, cancelable:Boolean = false, text:String = "") Creates an Event object that contains information about text events. | TextEvent
|  | clone():Event Creates a copy of the TextEvent object and sets the value of each property to match that of the original. | TextEvent
|  | formatToString(className:String, ... arguments):String A utility function for implementing the toString() method in your custom Event class. | Event
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isDefaultPrevented():Boolean Checks whether preventDefault() has been called on the event. | Event
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | preventDefault():void Cancels an event's default behavior if that behavior can be canceled. | Event
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | stopImmediatePropagation():void Prevents processing of any event listeners in the current node and any subsequent nodes in the event flow. | Event
|  | stopPropagation():void Prevents processing of any event listeners in nodes subsequent to the current node in the event flow. | Event
|  | toString():String Returns a string that contains all the properties of the TextEvent object. | TextEvent
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Public Constants
Hide Inherited Public Constants
Show Inherited Public Constants

| Constant | Defined By
--- | --- | ---
|  | ACTIVATE : String = "activate" [static] Defines the value of the type property of an activate event object. | Event
|  | ADDED : String = "added" [static] Defines the value of the type property of an added event object. | Event
|  | ADDED_TO_STAGE : String = "addedToStage" [static] Defines the value of the type property of an addedToStage event object. | Event
|  | CANCEL : String = "cancel" [static] Defines the value of the type property of a cancel event object. | Event
|  | CHANGE : String = "change" [static] Defines the value of the type property of a change event object. | Event
|  | CLEAR : String = "clear" [static] Defines the value of the type property of a clear event object. | Event
|  | CLOSE : String = "close" [static] Defines the value of the type property of a close event object. | Event
|  | COMPLETE : String = "complete" [static] Defines the value of the type property of a complete event object. | Event
|  | CONNECT : String = "connect" [static] Defines the value of the type property of a connect event object. | Event
|  | COPY : String = "copy" [static] Defines the value of the type property of a copy event object. | Event
|  | CUT : String = "cut" [static] Defines the value of the type property of a cut event object. | Event
|  | DEACTIVATE : String = "deactivate" [static] Defines the value of the type property of a deactivate event object. | Event
|  | ENTER_FRAME : String = "enterFrame" [static] Defines the value of the type property of an enterFrame event object. | Event
|  | EXIT_FRAME : String = "exitFrame" [static] Defines the value of the type property of an exitFrame event object. | Event
|  | FRAME_CONSTRUCTED : String = "frameConstructed" [static] Defines the value of the type property of an frameConstructed event object. | Event
|  | FULLSCREEN : String = "fullScreen" [static] Defines the value of the type property of a fullScreen event object. | Event
|  | ID3 : String = "id3" [static] Defines the value of the type property of an id3 event object. | Event
|  | INIT : String = "init" [static] Defines the value of the type property of an init event object. | Event
|  | LINK : String = "link" [static] Defines the value of the type property of a link event object. | TextEvent
|  | MOUSE_LEAVE : String = "mouseLeave" [static] Defines the value of the type property of a mouseLeave event object. | Event
|  | OPEN : String = "open" [static] Defines the value of the type property of an open event object. | Event
|  | PASTE : String = "paste" [static] Defines the value of the type property of a paste event object. | Event
|  | REMOVED : String = "removed" [static] Defines the value of the type property of a removed event object. | Event
|  | REMOVED_FROM_STAGE : String = "removedFromStage" [static] Defines the value of the type property of a removedFromStage event object. | Event
|  | RENDER : String = "render" [static] Defines the value of the type property of a render event object. | Event
|  | RESIZE : String = "resize" [static] Defines the value of the type property of a resize event object. | Event
|  | SAMPLE_DATA : String = "sampleData" [static] Defines the value of the type property of a sampleData event object. | Event
|  | SCROLL : String = "scroll" [static] Defines the value of the type property of a scroll event object. | Event
|  | SELECT : String = "select" [static] Defines the value of the type property of a select event object. | Event
|  | SELECT_ALL : String = "selectAll" [static] Defines the value of the type property of a selectAll event object. | Event
|  | SOUND_COMPLETE : String = "soundComplete" [static] Defines the value of the type property of a soundComplete event object. | Event
|  | TAB_CHILDREN_CHANGE : String = "tabChildrenChange" [static] Defines the value of the type property of a tabChildrenChange event object. | Event
|  | TAB_ENABLED_CHANGE : String = "tabEnabledChange" [static] Defines the value of the type property of a tabEnabledChange event object. | Event
|  | TAB_INDEX_CHANGE : String = "tabIndexChange" [static] Defines the value of the type property of a tabIndexChange event object. | Event
|  | TEXT_INPUT : String = "textInput" [static] Defines the value of the type property of a textInput event object. | TextEvent
|  | UNLOAD : String = "unload" [static] Defines the value of the type property of an unload event object. | Event

Property Detail

text | property

`text:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

For a `textInput` event, the character or sequence of characters entered by the user. For a `link` event, the text of the `event` attribute of the `href` attribute of the `<a>` tag.

Implementation
`public function get text():String`
`public function set text(value:String):void`
Example
The following code shows that the `link` event is dispatched when a user clicks the hypertext link:

     import flash.text.TextField;
     import flash.events.TextEvent;

     var tf:TextField = new TextField();
     tf.htmlText = "<a href='event:myEvent'>Click Me.</a>";
     tf.addEventListener("link", clickHandler);
     addChild(tf);

     function clickHandler(e:TextEvent):void {
      trace(e.type); // link
      trace(e.text); // myEvent
     }

Constructor Detail

TextEvent | () | Constructor

`public function TextEvent(type:String, bubbles:Boolean = false, cancelable:Boolean = false, text:String = "")`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Creates an Event object that contains information about text events. Event objects are passed as parameters to event listeners.

Parameters

| `type:String` — The type of the event. Event listeners can access this information through the inherited `type` property. Possible values are: `TextEvent.LINK` and `TextEvent.TEXT_INPUT`.
| `bubbles:Boolean` (default = `false`)`` — Determines whether the Event object participates in the bubbling phase of the event flow. Event listeners can access this information through the inherited `bubbles` property.
| `cancelable:Boolean` (default = `false`)`` — Determines whether the Event object can be canceled. Event listeners can access this information through the inherited `cancelable` property.
| `text:String` (default = "``")`` — One or more characters of text entered by the user. Event listeners can access this information through the `text` property.

See also

flash.text.TextField
Method Detail

clone | () | method

`override public function clone():Event`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Creates a copy of the TextEvent object and sets the value of each property to match that of the original.

Returns

| `Event` — A new TextEvent object with property values that match those of the original.

toString | () | method |

`override public function toString():String`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Returns a string that contains all the properties of the TextEvent object. The string is in the following format:

`[TextEvent type=value bubbles=value cancelable=value text=value]`

Returns

| `String` — A string that contains all the properties of the TextEvent object.

Constant Detail

LINK | Constant

`public static const LINK:String = "link"`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Defines the value of the `type` property of a `link` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `true`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The text field containing the hyperlink that has been clicked. The `target` is not always the object in the display list that registered the event listener. Use the `currentTarget` property to access the object in the display list that is currently processing the event.
`text` | The remainder of the URL after "event:"

See also

text
flash.text.TextField.link
Example
In this example, when a user clicks a hyperlink in HTML text, it triggers a text event. Depending on the link, the user is sent to a designated website based on the system's operating system, or a circle is drawn based on the user's selected radius.

A text field is created and its content is set to an HTML-formatted string by using the `htmlText` property. The links are underlined for easier identification by the user. (Adobe Flash Player changes the mouse pointer only after the pointer is over the link.) To make sure that the user's click invokes an ActionScript method, the URL of the link begins with the `"event:"` string and a listener is added for the `TextEvent.LINK` event.

The `linkHandler()` method that is triggered after the user clicks a link manages all the link events for the text field. The first if statement checks the `text` property of the event, which holds the remainder of the URL after the `"event:"` string. If the user clicked the link for the operating system, the name of the user's current operating system, taken from the system's `Capabilities.os` property, is used to send the user to the designated website. Otherwise, the selected radius size, passed by the event's `text` property, is used to draw a circle below the text field. Each time the user clicks the radius link, the previously drawn circle is cleared and a new red circle with the selected radius size is drawn.

    package {
        import flash.display.Sprite;
        import flash.events.TextEvent;
        import flash.errors.IOError;
        import flash.events.IOErrorEvent;
        import flash.system.Capabilities;
        import flash.net.navigateToURL;
        import flash.net.URLRequest;
        import flash.text.TextField;
        import flash.text.TextFieldAutoSize;
        import flash.display.Shape;
        import flash.display.Graphics;

        public class TextEvent_LINKExample extends Sprite {
            private  var myCircle:Shape = new Shape();

            public function TextEvent_LINKExample() {
                var myTextField:TextField = new TextField();
                myTextField.autoSize = TextFieldAutoSize.LEFT;
                myTextField.multiline = true;
                myTextField.background = true;
                myTextField.htmlText = "Draw a circle with the radius of <u><a href=\"event:20\">20 pixels</a></u>.<br>"
                             +  "Draw a circle with the radius of <u><a href=\"event:50\">50 pixels</a></u>.<br><br>"
                             +  "<u><a href=\"event:os\">Learn about your operating system.</a></u><br>";

                myTextField.addEventListener(TextEvent.LINK, linkHandler);

                this.addChild(myTextField);
                this.addChild(myCircle);
            }

            private function linkHandler(e:TextEvent):void {
                var osString:String = Capabilities.os;

                if(e.text == "os") {

                    if (osString.search(/Windows/) != -1 ){
                        navigateToURL(new URLRequest("http://www.microsoft.com/"), "_self");
                    }else if (osString.search(/Mac/) != -1 ) {
                        navigateToURL(new URLRequest("http://www.apple.com/"), "_self");
                    } else if (osString.search(/linux/i)!= -1) {
                        navigateToURL(new URLRequest("http://www.tldp.org/"), "_self");
                    }

                } else {
                    myCircle.graphics.clear();
                    myCircle.graphics.beginFill(0xFF0000);
                    myCircle.graphics.drawCircle(100, 150, Number(e.text));
                    myCircle.graphics.endFill();
                }
            }
        }
    }

TEXT_INPUT | Constant |

`public static const TEXT_INPUT:String = "textInput"`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Defines the value of the `type` property of a `textInput` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `true`
`cancelable` | `true`; call the `preventDefault()` method to cancel default behavior.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The text field into which characters are being entered. The target is not always the object in the display list that registered the event listener. Use the `currentTarget` property to access the object in the display list that is currently processing the event.
`text` | The character or sequence of characters entered by the user.

See also

flash.text.TextField.textInput
text
Example
The following example guides the user in generating a special combination key (similar to a password). This combination key has seven alphanumeric characters, where the second and fifth characters are numeric.

Three text fields for the preliminary instructions, the user input, and the warning (error) messages are created. An event listener is added to respond to the user's text input by triggering the `textInputHandler()` method. (Every time the user enters text, a `TextEvent.TEXT_INPUT` event is dispatched.

Note: The text events are dispatched when a user enters characters and not as a response to any keyboard input, such as backspace. To catch all keyboard events, use a listener for the `KeyboardEvent` event.)

The `textInputHandler()` method controls and manages the user input. The `preventDefault()` method is used to prevent Adobe Flash Player from immediately displaying the text in the input text field. The application is responsible for updating the field. To undo the user's deletion or modification to the characters already entered (the `result` string), the content of the input text field is reassigned to the `result` string when a user enters new characters. Also, to produce a consistent user experience, the `setSelection()` method places the insertion point (a caret) after the last selected character in the text field.

The first if statement in the `textInputHandler()` method checks the input for the second and fifth character positions of the combination key, which must be numbers. If the user input is correct, the `updateCombination()` method is called and the (`result`) combination key string is appended with the user input. The `updateCombination()` method also moves the insertion point after the selected character. After the seven characters are entered, the last if statement in the `textInputHandler()` method changes type of the `inputTextField` text field from `INPUT` to `DYNAMIC`, which means that the user can no longer enter or change any characters.

    package {
        import flash.display.Sprite;
        import flash.text.TextField;
        import flash.text.TextFieldType;
        import flash.text.TextFieldAutoSize;
        import flash.events.TextEvent;

        public class TextEvent_TEXT_INPUTExample extends Sprite {
            private var instructionTextField:TextField = new TextField();
            private var inputTextField:TextField = new TextField();
            private var warningTextField:TextField = new TextField();
            private var result:String = "";

            public function TextEvent_TEXT_INPUTExample() {
                instructionTextField.x = 10;
                instructionTextField.y = 10;
                instructionTextField.background = true;
                instructionTextField.autoSize = TextFieldAutoSize.LEFT;
                instructionTextField.text = "Please enter a value in the format A#AA#AA,\n"
                                            + "where 'A' represents a letter and '#' represents a number.\n" +
                                            "(Note that once you input a character you can't change it.)" ;

                inputTextField.x = 10;
                inputTextField.y = 70;
                inputTextField.height = 20;
                inputTextField.width = 75;
                inputTextField.background = true;
                inputTextField.border = true;
                inputTextField.type = TextFieldType.INPUT;

                warningTextField.x = 10;
                warningTextField.y = 100;
                warningTextField.autoSize = TextFieldAutoSize.LEFT;

                inputTextField.addEventListener(TextEvent.TEXT_INPUT, textInputHandler);

                this.addChild(instructionTextField);
                this.addChild(inputTextField);
                this.addChild(warningTextField);
            }

            private function textInputHandler(event:TextEvent):void {
                var charExp:RegExp = /[a-zA-z]/;
                var numExp:RegExp = /[0-9]/;

                event.preventDefault();

                inputTextField.text = result;
                inputTextField.setSelection(result.length + 1, result.length + 1);

                if (inputTextField.text.length == 1 || inputTextField.text.length == 4) {

                    if(numExp.test(event.text) == true) {
                        updateCombination(event.text);
                    } else {
                        warningTextField.text = "You need a single digit number.";
                    }

                }else {

                    if(charExp.test(event.text) == true) {
                        updateCombination(event.text);
                    } else {
                        warningTextField.text = "You need an alphabet character.";
                    }
                }

                if(inputTextField.text.length == 7) {
                    inputTextField.type = TextFieldType.DYNAMIC;
                    instructionTextField.text = "CONGRATULATIONS. You've done.";
                }
            }

            private function updateCombination(s:String):void {
                        warningTextField.text = "";
                        result += s;
                        inputTextField.text = result;
                        inputTextField.setSelection(result.length + 1, result.length + 1);
            }
        }
    }

Examples How to use examples
TextEventExample.as
The following example uses the TextEventExample class to create text fields and to listen for various text events on them. The example carries out the following tasks:

1. The example declares constants for two URLs to be used later.
2. The example declares two variables of type TextField to be used later.
3. The class constructor calls the following two methods:
   - `init()` initializes the TextField objects and add event listeners to them.
   - `draw()` adds the TextFields to the display list and assigns the text to be displayed.
4. The listeners `linkHandler()` and `textInputHandler()` react to the events according to their event type. The `linkHandler()` method opens a web browser if one is not open already and navigates to the clicked URL. The `textInputHandler()` method simply displays information every time a key is pressed in the associated text field.

Note: The domain shown in this example is fictitious and `[yourDomain]` should be replaced with a real domain.

    package {
        import flash.display.Sprite;
        import flash.text.TextField;
        import flash.text.TextFieldType;
        import flash.text.TextFieldAutoSize;
        import flash.events.TextEvent;
        import flash.events.TextEvent;
        import flash.net.URLRequest;
        import flash.net.navigateToURL;

        public class TextEventExample extends Sprite {
            private const DOMAIN_1_URL:String = "http://www.[yourDomain].com";
            private const DOMAIN_2_URL:String = "http://www.[yourDomain].com";
            private var linkTxt:TextField;
            private var textInputTxt:TextField;

            public function TextEventExample() {
                init();
                draw();
            }

            private function init():void {
                linkTxt = new TextField();
                linkTxt.addEventListener(TextEvent.LINK, linkHandler);
                linkTxt.height = 60;
                linkTxt.autoSize = TextFieldAutoSize.LEFT;
                linkTxt.multiline = true;

                textInputTxt = new TextField();
                textInputTxt.addEventListener(TextEvent.TEXT_INPUT, textInputHandler);
                textInputTxt.type = TextFieldType.INPUT;
                textInputTxt.background = true;
                textInputTxt.border = true;
                textInputTxt.height = 20;
            }

            private function draw():void {
                addChild(linkTxt);
                linkTxt.htmlText += createLink(DOMAIN_1_URL, "Click to go to first domain");
                linkTxt.htmlText += "<br />";
                linkTxt.htmlText += createLink(DOMAIN_2_URL, "Click to go to second domain");

                addChild(textInputTxt);
                textInputTxt.y = linkTxt.height;
                textInputTxt.text = "type here";
            }

            private function createLink(url:String, text:String):String {
                var link:String = "";
                link += "<font color='#0000FF'>";
                link += "<u>";
                link += "<b>";
                link += "<a href='event:" + url + "'>" + text + "</a>";
                link += "</b>";
                link += "</u>";
                link += "</font>";
                return link;
            }

            private function linkHandler(e:TextEvent):void {
                var request:URLRequest = new URLRequest(e.text);
                navigateToURL(request);
            }

            private function textInputHandler(e:TextEvent):void {
                trace(">> ============================");
                trace(">> e.text: " + e.text);
                trace(">> textInputTxt.text: " + textInputTxt.text);
            }
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00