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

Package | flash.events
Class | public class FocusEvent
Inheritance | FocusEvent Event Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Flash® Player dispatches FocusEvent objects when the user changes the focus from one object in the display list to another. There are four types of focus events:

- `FocusEvent.FOCUS_IN`
- `FocusEvent.FOCUS_OUT`
- `FocusEvent.KEY_FOCUS_CHANGE`
- `FocusEvent.MOUSE_FOCUS_CHANGE`

View the examples

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
|  | keyCode : uint The key code value of the key pressed to trigger a keyFocusChange event. | FocusEvent
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object
|  | relatedObject : InteractiveObject A reference to the complementary InteractiveObject instance that is affected by the change in focus. | FocusEvent
|  | shiftKey : Boolean Indicates whether the Shift key modifier is activated, in which case the value is true. | FocusEvent
|  | target : Object [read-only] The event target. | Event
|  | type : String [read-only] The type of event. | Event

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | FocusEvent(type:String, bubbles:Boolean = true, cancelable:Boolean = false, relatedObject:InteractiveObject = null, shiftKey:Boolean = false, keyCode:uint = 0) Creates an Event object with specific information relevant to focus events. | FocusEvent
|  | clone():Event Creates a copy of the FocusEvent object and sets the value of each property to match that of the original. | FocusEvent
|  | 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 FocusEvent object. | FocusEvent
|  | 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
|  | FOCUS_IN : String = "focusIn" [static] Defines the value of the type property of a focusIn event object. | FocusEvent
|  | FOCUS_OUT : String = "focusOut" [static] Defines the value of the type property of a focusOut event object. | FocusEvent
|  | 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
|  | KEY_FOCUS_CHANGE : String = "keyFocusChange" [static] Defines the value of the type property of a keyFocusChange event object. | FocusEvent
|  | MOUSE_FOCUS_CHANGE : String = "mouseFocusChange" [static] Defines the value of the type property of a mouseFocusChange event object. | FocusEvent
|  | 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
|  | UNLOAD : String = "unload" [static] Defines the value of the type property of an unload event object. | Event

Property Detail

keyCode | property

`keyCode:uint` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The key code value of the key pressed to trigger a `keyFocusChange` event.

Implementation
`public function get keyCode():uint`
`public function set keyCode(value:uint):void`

relatedObject | property |

`relatedObject:InteractiveObject` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

A reference to the complementary InteractiveObject instance that is affected by the change in focus. For example, when a `focusOut` event occurs, the `relatedObject` represents the InteractiveObject instance that has gained focus.

Implementation
`public function get relatedObject():InteractiveObject`
`public function set relatedObject(value:InteractiveObject):void`

shiftKey | property |

`shiftKey:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Indicates whether the Shift key modifier is activated, in which case the value is `true`. Otherwise, the value is `false`. This property is used only if the FocusEvent is of type `keyFocusChange`.

Implementation
`public function get shiftKey():Boolean`
`public function set shiftKey(value:Boolean):void`
Constructor Detail

FocusEvent | () | Constructor

`public function FocusEvent(type:String, bubbles:Boolean = true, cancelable:Boolean = false, relatedObject:InteractiveObject = null, shiftKey:Boolean = false, keyCode:uint = 0)`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Creates an Event object with specific information relevant to focus events. Event objects are passed as parameters to event listeners.

Parameters

| `type:String` — The type of the event. Possible values are: `FocusEvent.FOCUS_IN`, `FocusEvent.FOCUS_OUT`, `FocusEvent.KEY_FOCUS_CHANGE`, and `FocusEvent.MOUSE_FOCUS_CHANGE`.
| `bubbles:Boolean` (default = `true`)`` — Determines whether the Event object participates in the bubbling stage of the event flow.
| `cancelable:Boolean` (default = `false`)`` — Determines whether the Event object can be canceled.
| `relatedObject:InteractiveObject` (default = `null`)`` — Indicates the complementary InteractiveObject instance that is affected by the change in focus. For example, when a `focusIn` event occurs, `relatedObject` represents the InteractiveObject that has lost focus.
| `shiftKey:Boolean` (default = `false`)`` — Indicates whether the Shift key modifier is activated.
| `keyCode:uint` (default = `0`)`` — Indicates the code of the key pressed to trigger a `keyFocusChange` event.

See also

FOCUS_IN
FOCUS_OUT
KEY_FOCUS_CHANGE
MOUSE_FOCUS_CHANGE
Method Detail

clone | () | method

`override public function clone():Event`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

Returns

| `Event` — A new FocusEvent 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 FocusEvent object. The string is in the following format:

`[FocusEvent type=value bubbles=value cancelable=value relatedObject=value shiftKey=value]`

Returns

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

Constant Detail

FOCUS_IN | Constant

`public static const FOCUS_IN:String = "focusIn"`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Defines the value of the `type` property of a `focusIn` 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.
`keyCode` | 0; applies only to `keyFocusChange` events.
`relatedObject` | The complementary InteractiveObject instance that is affected by the change in focus.
`shiftKey` | `false`; applies only to `keyFocusChange` events.
`target` | The InteractiveObject instance that has just received focus. 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.

See also

flash.display.InteractiveObject.focusIn

FOCUS_OUT | Constant |

`public static const FOCUS_OUT:String = "focusOut"`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Defines the value of the `type` property of a `focusOut` 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.
`keyCode` | 0; applies only to `keyFocusChange` events.
`relatedObject` | The complementary InteractiveObject instance that is affected by the change in focus.
`shiftKey` | `false`; applies only to `keyFocusChange` events.
`target` | The InteractiveObject instance that has just lost focus. 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.

See also

flash.display.InteractiveObject.focusOut

KEY_FOCUS_CHANGE | Constant |

`public static const KEY_FOCUS_CHANGE:String = "keyFocusChange"`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Defines the value of the `type` property of a `keyFocusChange` 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.
`keyCode` | The key code value of the key pressed to trigger a `keyFocusChange` event.
`relatedObject` | The complementary InteractiveObject instance that is affected by the change in focus.
`shiftKey` | `true` if the Shift key modifier is activated; `false` otherwise.
`target` | The InteractiveObject instance that currently has focus. 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.

See also

flash.display.InteractiveObject.keyFocusChange

MOUSE_FOCUS_CHANGE | Constant |

`public static const MOUSE_FOCUS_CHANGE:String = "mouseFocusChange"`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Defines the value of the `type` property of a `mouseFocusChange` 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.
`keyCode` | 0; applies only to `keyFocusChange` events.
`relatedObject` | The complementary InteractiveObject instance that is affected by the change in focus.
`shiftKey` | `false`; applies only to `keyFocusChange` events.
`target` | The InteractiveObject instance that currently has focus. 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.

See also

flash.display.InteractiveObject.mouseFocusChange
Examples How to use examples
FocusEventExample.as
The following example uses the `FocusEventExample` and `CustomSprite` classes to show how focus can be used in conjunction with items drawn on the Stage to capture events and print information. This example carries out the following tasks:

1. It declares the properties `child` (of type Sprite) and `childCount` (of type uint).
2. A `for` loop creates five light blue squares at (0,0). It begins by assigning `child` to a new CustomSprite instance. Each time a CustomSprite object is created, the following happens:
   - The `size` property of type uint is set to 50 pixels and `bgColor` is set to light blue.
   - The `buttonMode` and `useHandCursor` properties of the Sprite class are set to `true` within the constructor.
   - An event listener of type `click` is instantiated, along with the associated subscriber `clickHandler()`. The subscriber method creates a local variable `target` of type Sprite and assigns it whichever box was clicked. The Stage's focus is then assigned to `target`.
   - The `draw()` method is called, which creates a 50 x 50 pixel square by calling the `beginFill()`, `drawRect()`, and `endFill()` methods of the Graphics class and the instance properties.
3. In the for loop, the `configureListeners()` method is called, which instantiates three event listeners/subscribers:
   - `focusIn`/`focusInHandler()` is dispatched after the `click` event for whichever display list object (box) is clicked.
   - `focusOut`/`focusOutHandler()` is dispatched when another box is clicked or if the focus leaves the Stage (for example, by clicking outside Flash Player).
   - `keyFocusChange`/`keyFocusChangeHandler()` is dispatched if you use the Tab key or the left-arrow or right-arrow keys to select a display list object. The `keyFocusChangeHandler()` method traps the left-arrow and right-arrow keys, however, and calls the `preventDefault()` method to disable them.
4. In the `for` loop, each square is added to the display list and displayed (all in the same area) by means of `addChild()`.
5. The constructor then calls `refreshLayout()`, which distributes the orange squares across the top (y = 0) of the display with 5 pixels separating each square.

    package {
        import flash.display.Sprite;
        import flash.display.DisplayObject;
        import flash.events.FocusEvent;
        import flash.events.IEventDispatcher;

        public class FocusEventExample extends Sprite {
            private var gutter:uint = 5;
            private var childCount:uint = 5;

            public function FocusEventExample() {
                var child:Sprite;
                for(var i:uint; i < childCount; i++) {
                    child = new CustomSprite();
                    configureListeners(child);
                    addChild(child);
                }
                refreshLayout();
            }

            private function configureListeners(dispatcher:IEventDispatcher):void {
                dispatcher.addEventListener(FocusEvent.FOCUS_IN, focusInHandler);
                dispatcher.addEventListener(FocusEvent.FOCUS_OUT, focusOutHandler);
                dispatcher.addEventListener(FocusEvent.KEY_FOCUS_CHANGE, keyFocusChangeHandler);
                dispatcher.addEventListener(FocusEvent.MOUSE_FOCUS_CHANGE, mouseFocusChangeHandler);
            }

            private function refreshLayout():void {
                var ln:uint = numChildren;
                var child:DisplayObject = getChildAt(0);
                var lastChild:DisplayObject = child;
                for(var i:uint = 1; i < ln; i++) {
                    child = getChildAt(i);
                    child.x = lastChild.x + lastChild.width + gutter;
                    lastChild = child;
                }
            }

            private function focusInHandler(event:FocusEvent):void {
                var target:CustomSprite = CustomSprite(event.target);
                trace("focusInHandler: " + target.name);
            }

            private function focusOutHandler(event:FocusEvent):void {
                var target:CustomSprite = CustomSprite(event.target);
                trace("focusOutHandler: " + target.name);
            }

            private function keyFocusChangeHandler(event:FocusEvent):void {
                if(event.keyCode == 39 || event.keyCode == 37){
                    event.preventDefault()
                }
                var target:CustomSprite = CustomSprite(event.target);
                trace("keyFocusChangeHandler: " + target.name);
            }
            private function mouseFocusChangeHandler(event:FocusEvent):void {
                var target:CustomSprite = CustomSprite(event.target);
                trace("mouseFocusChangeHandler: " + target.name);
            }
        }
    }

    import flash.display.Sprite;
    import flash.events.MouseEvent;

    class CustomSprite extends Sprite {
        private var size:uint = 50;
        private var bgColor:uint = 0x00CCFF;

        public function CustomSprite() {
            buttonMode = true;
            useHandCursor = true;
            addEventListener(MouseEvent.CLICK, clickHandler);
            draw(size, size);
        }

        private function draw(w:uint, h:uint):void {
            graphics.beginFill(bgColor);
            graphics.drawRect(0, 0, w, h);
            graphics.endFill();
        }

        private function clickHandler(event:MouseEvent):void {
            var target:Sprite = Sprite(event.target);
            trace("clickHandler: " + target.name);
            stage.focus = target;
        }
    }

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