flash.events

# FocusEvent - AS3

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

An object dispatches a FocusEvent object 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
|  | direction : String Specifies direction of focus for a focusIn event. | FocusEvent
|  | eventPhase : uint [read-only] The current phase in the event flow. | Event
|  | isRelatedObjectInaccessible : Boolean If true, the relatedObject property is set to null for reasons related to security sandboxes. | FocusEvent
|  | keyCode : uint The key code value of the key pressed to trigger a keyFocusChange event. | FocusEvent
|  | 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, direction:String = "none") Creates an Event object with specific information relevant to focus events. | FocusEvent
|  | clone():Event [override] 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 custom ActionScript 3.0 Event classes. | Event
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isDefaultPrevented():Boolean Checks whether the preventDefault() method 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
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String [override] 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
--- | --- | ---
|  | 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
|  | 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

Property Detail

### direction

property

`direction:String`

Runtime Versions: | AIR 1.0, Flash Lite 4

Specifies direction of focus for a `focusIn` event.

Implementation
`public function get direction():String`
`public function set direction(value:String):void`

Related API Elements

flash.display.FocusDirection
flash.display.Stage.assignFocus()

### isRelatedObjectInaccessible

property

`isRelatedObjectInaccessible:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 10, Flash Lite 4

If `true`, the `relatedObject` property is set to `null` for reasons related to security sandboxes. If the nominal value of `relatedObject` is a reference to a DisplayObject in another sandbox, `relatedObject` is set to `null` unless there is permission in both directions across this sandbox boundary. Permission is established by calling `Security.allowDomain()` from a SWF file, or by providing a policy file from the server of an image file, and setting the `LoaderContext.checkPolicyFile` property when loading the image.

Implementation
`public function get isRelatedObjectInaccessible():Boolean`
`public function set isRelatedObjectInaccessible(value:Boolean):void`

Related API Elements

FocusEvent.relatedObject
Security.allowDomain()
LoaderContext.checkPolicyFile

### keyCode

property

`keyCode:uint`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

The value of this property can be `null` in two circumstances: if there no related object, or there is a related object, but it is in a security sandbox to which you don't have access. Use the `isRelatedObjectInaccessible()` property to determine which of these reasons applies.

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

Related API Elements

FocusEvent.isRelatedObjectInaccessible

### shiftKey

property

`shiftKey:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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, direction:String = "none")`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.
| `direction:String` (default = "`none`")`` — Indicates from which direction the target interactive object is being activated. Set to `FocusDirection.NONE` (the default value) for all events other than `focusIn`.

Related API Elements

FOCUS_IN
FOCUS_OUT
KEY_FOCUS_CHANGE
MOUSE_FOCUS_CHANGE
flash.display.FocusDirection
Method Detail

### clone

()
method

`override public function clone():Event`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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] keyCode=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

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.
`direction` | The direction from which focus was assigned. This property reports the value of the `direction` parameter of the `assignFocus()` method of the stage. If the focus changed through some other means, the value will always be `FocusDirection.NONE`. Applies only to `focusIn` events. For all other focus events the value will be `FocusDirection.NONE`.

Related API Elements

flash.display.InteractiveObject.focusIn

### FOCUS_OUT

Constant

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

Related API Elements

flash.display.InteractiveObject.focusOut

### KEY_FOCUS_CHANGE

Constant

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

Related API Elements

flash.display.InteractiveObject.keyFocusChange

### MOUSE_FOCUS_CHANGE

Constant

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

Related API Elements

flash.display.InteractiveObject.mouseFocusChange
Examples How to use this example
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.

Copy

    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;
        }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00