fl.managers

# FocusManager - AS3 Flash

Package | fl.managers
Class | public class FocusManager
Inheritance | FocusManager Object
Implements | IFocusManager

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

The FocusManager class manages focus for a set of components that are navigated by mouse or keyboard as a tab loop.

A tab loop is typically navigated by using the Tab key; focus moves between the components in the tab loop in a circular pattern from the first component that has focus, to the last, and then back again to the first. A tab loop includes all the components and tab-enabled components in a container. An application can contain numerous tab loops.

A FocusManager instance is responsible for a single tab loop; an application uses a different FocusManager instance to manage each tab loop that it contains, although a main application is always associated with at least one FocusManager instance. An application may require additional FocusManager instances if it includes a popup window, for example, that separately contains one or more tab loops of components.

All components that can be managed by a FocusManager instance must implement the fl.managers.IFocusManagerComponent interface. Objects for which Flash Player manages focus are not required to implement the IFocusManagerComponent interface.

The FocusManager class also manages how the default button is implemented. A default button dispatches a `click` event when the Enter key is pressed on a form, depending on where focus is at the time. The default button does not dispatch the `click` event if a text area has focus or if a value is being edited in a component, for example, in a ComboBox or NumericStepper component.

View the examples

Related API Elements

IFocusManager
IFocusManagerComponent

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | defaultButton : Button Gets or sets the current default button. | FocusManager
|  | defaultButtonEnabled : Boolean Gets or sets a value that indicates whether the default button is enabled. | FocusManager
|  | form : DisplayObjectContainer Base DisplayObjectContainer for the IFocusManager, usually the stage. | FocusManager
|  | nextTabIndex : int [read-only] Gets the next unique tab index to use in this tab loop. | FocusManager
|  | showFocusIndicator : Boolean Gets or sets a value that indicates whether a component that has focus should be marked with a visual indicator of focus. | FocusManager

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | FocusManager(container:DisplayObjectContainer) Creates a new FocusManager instance. | FocusManager
|  | activate():void Activates the FocusManager instance. | FocusManager
|  | deactivate():void Deactivates the FocusManager. | FocusManager
|  | findFocusManagerComponent(component:InteractiveObject):InteractiveObject Retrieves the interactive object that contains the given object, if any. | FocusManager
|  | getFocus():InteractiveObject Gets the interactive object that currently has focus. | FocusManager
|  | getNextFocusManagerComponent(backward:Boolean = false):InteractiveObject Retrieves the interactive object that would receive focus if the user pressed the Tab key to navigate to the next object. | FocusManager
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | hideFocus():void Sets the showFocusIndicator value to false and removes the visual focus indicator from the object that has focus, if any. | FocusManager
|  | 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
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setFocus(component:InteractiveObject):void Sets focus on an IFocusManagerComponent component. | FocusManager
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | showFocus():void Sets the showFocusIndicator value to true and draws the visual focus indicator on the object with focus, if any. | FocusManager
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

### defaultButton

property

`defaultButton:Button`

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Gets or sets the current default button.

The default button is the button on a form that dispatches a `click` event when the Enter key is pressed, depending on where focus is at the time.

Implementation
`public function get defaultButton():Button`
`public function set defaultButton(value:Button):void`

### defaultButtonEnabled

property

`defaultButtonEnabled:Boolean`

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Gets or sets a value that indicates whether the default button is enabled. If this value is set to `true`, the focus manager monitors the Enter key and dispatches a `click` event on the default button if the Enter key is pressed when a component that is not a Button component has focus. If this value is set to `false`, the focus manager does not monitor the Enter key. Components that use the Enter key set this property to `false` to prevent a `click` event from being dispatched on the default button, if one exists, when a user presses the Enter key.

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

### form

property

`form:DisplayObjectContainer`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9.0.28.0

Base DisplayObjectContainer for the IFocusManager, usually the stage.

Implementation
`public function get form():DisplayObjectContainer`
`public function set form(value:DisplayObjectContainer):void`

### nextTabIndex

property

`nextTabIndex:int` [read-only]

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Gets the next unique tab index to use in this tab loop.

Implementation
`public function get nextTabIndex():int`

### showFocusIndicator

property

`showFocusIndicator:Boolean`

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Gets or sets a value that indicates whether a component that has focus should be marked with a visual indicator of focus.

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

### FocusManager

()
Constructor

`public function FocusManager(container:DisplayObjectContainer)`

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Creates a new FocusManager instance.

A focus manager manages focus within the children of a DisplayObjectContainer object.

Parameters

| `container:DisplayObjectContainer` — A DisplayObjectContainer that hosts the focus manager, or `stage`.

Method Detail

### activate

()
method

`public function activate():void`

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Activates the FocusManager instance.

The FocusManager instance adds event handlers that allow it to monitor focus-related keyboard and mouse activity.

### deactivate

()
method

`public function deactivate():void`

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Deactivates the FocusManager.

The FocusManager removes the event handlers that allow it to monitor focus-related keyboard and mouse activity.

### findFocusManagerComponent

()
method

`public function findFocusManagerComponent(component:InteractiveObject):InteractiveObject`

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Retrieves the interactive object that contains the given object, if any. The player can set focus to a subcomponent of a Flash component; this method determines which interactive object has focus from the component perspective.

Parameters

| `component:InteractiveObject` — An object that can have player-level focus.

Returns

| `InteractiveObject` — The object containing the `component` or, if one is not found, the `component` itself.

### getFocus

()
method

`public function getFocus():InteractiveObject`

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Gets the interactive object that currently has focus. Adobe recommends calling this method instead of using the Stage object because this method indicates which component has focus. The Stage might return a subcomponent in that component.

Returns

| `InteractiveObject` — The interactive object that currently has focus.

### getNextFocusManagerComponent

()
method

`public function getNextFocusManagerComponent(backward:Boolean = false):InteractiveObject`

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Retrieves the interactive object that would receive focus if the user pressed the Tab key to navigate to the next object. This method retrieves the object that currently has focus if there are no other valid objects in the application.

Parameters

| `backward:Boolean` (default = `false`)`` — If this parameter is set to `true`, focus moves in a backward direction, causing this method to retrieve the object that would receive focus next if the Shift+Tab key combination were pressed.

Returns

| `InteractiveObject` — The next component to receive focus.

### hideFocus

()
method

`public function hideFocus():void`

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Sets the `showFocusIndicator` value to `false` and removes the visual focus indicator from the object that has focus, if any.

### setFocus

()
method

`public function setFocus(component:InteractiveObject):void`

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Sets focus on an IFocusManagerComponent component. This method does not check for component visibility, enabled state, or other conditions.

Parameters

| `component:InteractiveObject` — An object that can receive focus.

### showFocus

()
method

`public function showFocus():void`

Language Version: | ActionScript 3.0

Product Version: | Flash CS3

Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0

Sets the `showFocusIndicator` value to `true` and draws the visual focus indicator on the object with focus, if any.

Examples How to use this example
FocusManagerExample.as
This example demonstrates how to use the FocusManager class to change focus between components on the Stage.

To run the example, follow these steps:

1. Add the TextInput component to the library.
2. Save this code as FocusManagerExample.as in the same directory as your FLA file.
3. Set the Document class in the FLA file to FocusManagerExample.

Copy

    package
    {
        import fl.controls.TextInput;
        import fl.managers.FocusManager;
        import flash.display.InteractiveObject;
        import flash.display.Sprite;
        import flash.events.*;
        import flash.utils.Timer;

        public class FocusManagerExample extends Sprite
        {
            private var fm:FocusManager;

            public function FocusManagerExample() {
                buildGridOfTextInputs();

                fm = new FocusManager(this);
                var t:Timer = new Timer(1000);
                t.addEventListener(TimerEvent.TIMER,secondPassed);
                t.start();
            }
            private function buildGridOfTextInputs():void {
                var rowSpacing:uint = 30;
                var colSpacing:uint = 110;
                var totalRows:uint = 4;
                var totalCols:uint = 3;
                var i:uint;

                for(i = 0; i < totalRows * totalCols; i++) {
                    var ti:TextInput = new TextInput()
                    ti.name = "component"+i.toString();
                    ti.addEventListener(FocusEvent.FOCUS_IN,focusChange);
                    ti.setSize(100,20);
                    ti.x = 10 + ((i % totalCols) * colSpacing);
                    ti.y = 10 + (Math.floor(i / totalCols) * rowSpacing);
                    ti.tabEnabled = true;
                    addChild(ti);
                }
            }
            private function secondPassed(e:TimerEvent):void {
                var nextComponent:InteractiveObject = fm.getNextFocusManagerComponent();
                fm.setFocus(nextComponent);
            }

            private function focusChange(e:FocusEvent):void {
                trace("Focus change: " + e.target.name);
            }
        }
    }

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