Packagemx.managers
Classpublic class FocusManager
InheritanceFocusManager Inheritance Object
Implements IFocusManager

The FocusManager class manages the focus on components in response to mouse activity or keyboard activity (Tab key). There can be several FocusManager instances in an application. Each FocusManager instance is responsible for a set of components that comprise a "tab loop". If you hit Tab enough times, focus traverses through a set of components and eventually get back to the first component that had focus. That is a "tab loop" and a FocusManager instance manages that loop. If there are popup windows with their own set of components in a "tab loop" those popup windows will have their own FocusManager instances. The main application always has a FocusManager instance.

The FocusManager manages focus from the "component level". In Flex, a UITextField in a component is the only way to allow keyboard entry of text. To the Flash Player or AIR, that UITextField has focus. However, from the FocusManager's perspective the component that parents the UITextField has focus. Thus there is a distinction between component-level focus and player-level focus. Application developers generally only have to deal with component-level focus while component developers must understand player-level focus.

All components that can be managed by the FocusManager must implement mx.managers.IFocusManagerComponent, whereas objects managed by player-level focus do not.

The FocusManager also managers the concept of a defaultButton, which is the Button on a form that dispatches a click event when the Enter key is pressed depending on where focus is at that time.


Public Properties
 PropertyDefined By
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  defaultButton : IButton
A reference to the original default Button control.
FocusManager
  defaultButtonEnabled : Boolean
A flag that indicates whether the FocusManager should check for the Enter key being pressed to activate the default button.
FocusManager
  focusPane : Sprite
A single Sprite that is moved from container to container as the focus moves to those containers.
FocusManager
  nextTabIndex : int
[read-only] The next unique tab index to use in this tab loop.
FocusManager
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  showFocusIndicator : Boolean
A flag that indicates whether to display an indicator that a component has focus.
FocusManager
Public Methods
 MethodDefined By
  
FocusManager(container:IFocusManagerContainer, popup:Boolean = false)
Constructor.
FocusManager
  
activate():void
The SystemManager activates and deactivates a FocusManager if more than one IFocusManagerContainer is visible at the same time.
FocusManager
  
addSWFBridge(bridge:IEventDispatcher, owner:DisplayObject):void
This is called on the top-level focus manager and the parent focus manager for each new bridge of focusable content created.
FocusManager
  
deactivate():void
The SystemManager activates and deactivates a FocusManager if more than one IFocusManagerContainer is visible at the same time.
FocusManager
  
findFocusManagerComponent(o:InteractiveObject):IFocusManagerComponent
Returns the IFocusManagerComponent that contains the given object, if any.
FocusManager
  
getFocus():IFocusManagerComponent
Gets the IFocusManagerComponent component that currently has the focus.
FocusManager
  
getNextFocusManagerComponent(backward:Boolean = false):IFocusManagerComponent
Returns the IFocusManagerComponent that would receive focus if the user pressed the Tab key to navigate to another component.
FocusManager
 Inherited
hasOwnProperty(name:String):Boolean
Indicates whether an object has a specified property defined.
Object
  
hideFocus():void
Sets showFocusIndicator to false and removes the visual focus indicator from the focused object, if any.
FocusManager
 Inherited
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
  
moveFocus(direction:String, fromDisplayObject:DisplayObject = null):void
Move focus from the current control to the previous or next control in the tab order.
FocusManager
 Inherited
propertyIsEnumerable(name:String):Boolean
Indicates whether the specified property exists and is enumerable.
Object
  
removeSWFBridge(bridge:IEventDispatcher):void
FocusManager
  
setFocus(o:IFocusManagerComponent):void
Sets focus to an IFocusManagerComponent component.
FocusManager
 Inherited
setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void
Sets the availability of a dynamic property for loop operations.
Object
  
showFocus():void
Sets showFocusIndicator to true and draws the visual focus indicator on the focused object, if any.
FocusManager
 Inherited
toLocaleString():String
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
  
toString():String
Returns a String representation of the component hosting the FocusManager object, with the String ".focusManager" appended to the end of the String.
FocusManager
 Inherited
valueOf():Object
Returns the primitive value of the specified object.
Object
Property Detail
defaultButtonproperty
defaultButton:IButton

A reference to the original default Button control. Pressing the Enter key while the focus is on any control activates the Button control by dispatching a click event on the Button control, just as if it was clicked with the mouse. The actual default Button control changes if focus is given to another Button control, but switches back to the original if focus is not on a button.

This property is managed by Flex containers; do not set it directly to specify the default button.

The defaultButton must be of class mx.controls.Button even though this property is of type IUIComponent.



Implementation
    public function get defaultButton():IButton
    public function set defaultButton(value:IButton):void
defaultButtonEnabledproperty 
defaultButtonEnabled:Boolean

A flag that indicates whether the FocusManager should check for the Enter key being pressed to activate the default button. TextArea and other components that want to recognize the Enter key set this property to false to disable the Enter key from dispatching a click event on the default button, if it exists.



Implementation
    public function get defaultButtonEnabled():Boolean
    public function set defaultButtonEnabled(value:Boolean):void
focusPaneproperty 
focusPane:Sprite

A single Sprite that is moved from container to container as the focus moves to those containers. The Sprite is used as the parent of the visual indicator that a component has focus.



Implementation
    public function get focusPane():Sprite
    public function set focusPane(value:Sprite):void
nextTabIndexproperty 
nextTabIndex:int  [read-only]

The next unique tab index to use in this tab loop.



Implementation
    public function get nextTabIndex():int
showFocusIndicatorproperty 
showFocusIndicator:Boolean

A flag that indicates whether to display an indicator that a component has focus. If true a component receiving focus draws a visible indicator that it has focus.

By default, this is false until the user uses the Tab key, then it is set to true.

In general it is better to use the showFocus() and hideFocus() methods to change this property as those methods also update the visual indicator that a component has focus.



Implementation
    public function get showFocusIndicator():Boolean
    public function set showFocusIndicator(value:Boolean):void
Constructor Detail
FocusManager()Constructor
public function FocusManager(container:IFocusManagerContainer, popup:Boolean = false)

Constructor.

A FocusManager manages the focus within the children of an IFocusManagerContainer. It installs itself in the IFocusManagerContainer during execution of the constructor.

Parameters
container:IFocusManagerContainer — An IFocusManagerContainer that hosts the FocusManager.
 
popup:Boolean (default = false) — If true, indicates that the container is a popup component and not the main application.
Method Detail
activate()method
public function activate():void

The SystemManager activates and deactivates a FocusManager if more than one IFocusManagerContainer is visible at the same time. If the mouse is clicked in an IFocusManagerContainer with a deactivated FocusManager, the SystemManager will call the activate() method on that FocusManager. The FocusManager that was activated will have its deactivate() method called prior to the activation of another FocusManager.

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

addSWFBridge()method 
public function addSWFBridge(bridge:IEventDispatcher, owner:DisplayObject):void

This is called on the top-level focus manager and the parent focus manager for each new bridge of focusable content created. When the parent focus manager of the new focusable content is called, focusable content will become part of the tab order. When the top-level focus manager is called the bridge becomes one of the focus managers managed by the top-level focus manager.

Parameters

bridge:IEventDispatcher
 
owner:DisplayObject

deactivate()method 
public function deactivate():void

The SystemManager activates and deactivates a FocusManager if more than one IFocusManagerContainer is visible at the same time. If the mouse is clicked in an IFocusManagerContainer with a deactivated FocusManager, the SystemManager will call the activate() method on that FocusManager. The FocusManager that was activated will have its deactivate() method called prior to the activation of another FocusManager.

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

findFocusManagerComponent()method 
public function findFocusManagerComponent(o:InteractiveObject):IFocusManagerComponent

Returns the IFocusManagerComponent that contains the given object, if any. Because the player can set focus to a subcomponent of a Flex component this method determines which IFocusManagerComponent has focus from the component perspective.

Parameters

o:InteractiveObject — An object that can have player-level focus.

Returns
IFocusManagerComponent — The IFOcusManagerComponent containing o or null
getFocus()method 
public function getFocus():IFocusManagerComponent

Gets the IFocusManagerComponent component that currently has the focus. Calling this method is recommended instead of using the Stage object because it indicates which component has focus. The Stage might return a subcomponent in that component.

Returns
IFocusManagerComponent — IFocusManagerComponent object that has focus.
getNextFocusManagerComponent()method 
public function getNextFocusManagerComponent(backward:Boolean = false):IFocusManagerComponent

Returns the IFocusManagerComponent that would receive focus if the user pressed the Tab key to navigate to another component. It will return the same component as the current focused component if there are no other valid components in the application.

Parameters

backward:Boolean (default = false) — If true, return the object as if the Shift-Tab keys were pressed.

Returns
IFocusManagerComponent — The component that would receive focus.
hideFocus()method 
public function hideFocus():void

Sets showFocusIndicator to false and removes the visual focus indicator from the focused object, if any.

moveFocus()method 
public function moveFocus(direction:String, fromDisplayObject:DisplayObject = null):void

Move focus from the current control to the previous or next control in the tab order. The direction of the move is specified with the direction argument.

Parameters

direction:String — FocusRequestDirection.FORWARD moves to from the control that currently has focus to controls with a higher tab index. If more than one control has the same index, the next control in the flow of the document is visited. FocusRequestDirection.BACKWARD moves to controls with a lower tab index. FocusRequestDirection.TOP move the focus to the control with the lowest tab index. If more than one control has the same index, focus is moved to the first control in the flow of the document. FocusRequestDirection.BOTTOM move the focus to the control with the highest tab index. If more than one control has the same index, focus is moved to the last control in the flow of the document.
 
fromDisplayObject:DisplayObject (default = null) — The starting point from which focus is moved. If an object is provided, this overrides the default behavior where focus is moved from the object that currently has focus.

removeSWFBridge()method 
public function removeSWFBridge(bridge:IEventDispatcher):void

Parameters

bridge:IEventDispatcher

setFocus()method 
public function setFocus(o:IFocusManagerComponent):void

Sets focus to an IFocusManagerComponent component. Does not check for the components visibility, enabled state, or any other conditions.

Parameters

o:IFocusManagerComponent — A component that can receive focus.

showFocus()method 
public function showFocus():void

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

toString()method 
public function toString():String

Returns a String representation of the component hosting the FocusManager object, with the String ".focusManager" appended to the end of the String.

Returns
String — Returns a String representation of the component hosting the FocusManager object, with the String ".focusManager" appended to the end of the String.



© 2009 Adobe Systems Incorporated. All rights reserved.
Thu Aug 13 2009, 03:11 AM -07:00