Keyboard focus management in Feathers
In desktop apps, users expect to be able to use the Tab key to navigate between UI controls, and they expect to be able to use the keyboard to do things like press buttons or adjust sliders. Feathers provides completely optional focus management support with the FocusManager
class, if your app needs these capabilities.
In general, you should only enable focus management in desktop apps. Some mobile components are not optimized for focus management.
Enabling the Focus Manager
To enable focus management, only one line is required when your app first starts up:
FocusManager.setEnabledForStage( this.stage, true );
That's it! You will be able to use Tab and Shift+Tab to navigate between controls in your app.
If you are building an AIR desktop app with multiple Starling instances in multiple windows, you will need to enable focus management for each stage with separate calls to setEnabledForStage()
.
Changing Focus Programmatically
You can manually updated the focused component, if you desire:
var focusManager:IFocusManager = FocusManager.getFocusManagerForStage( this.stage );
focusManager.focus = button;
It's as simple as setting the focus
property on the IFocusManager
.
To clear focus, set this property to null
:
var focusManager:IFocusManager = FocusManager.getFocusManagerForStage( this.stage );
focusManager.focus = null;
Customizing focus order
By default, when the user changes focus with the keyboard, Feathers will pass focus using display list ordering. Using getChildIndex()
and other standard display list APIs, the focus manager will search the display list in a relatively intuitive order to find the next (or previous) child that can receive focus.
If things end up a bit out of the ordering that you expected, you can customize the focus order using the nextTabFocus
and previousTabFocus
properties:
var button1:Button = new Button();
this.addChild( button1 );
var button2:Button = new Button();
this.addChild( button2 );
button1.nextTabFocus = button2;
button2.previousTabFocus = button1;
Focus and pop-Ups
The focus manager and the pop-up manager know how to communicate. If a pop-up is modal, a new focus manager will be created and it will gain exclusive control over keyboard focus. Until the modal pop-up is closed, nothing below the modal overlay will be able to receive focus. Multiple modal pop-ups will add additional focus managers to the stack that will ensure that each modal layer blocks keyboard focus to anything below.
If a pop-up is not modal, then the same focus manager will remain active and everything will be able to receive focus, including the pop-up and everything below the pop-up.