FocusCycler

class

A utility class that helps cycling over focusable views in a ViewCollection when the focus is tracked by the FocusTracker instance. It helps implementing keyboard navigation in HTML forms, toolbars, lists and the like.

To work properly it requires:

a collection of focusable (HTML tabindex attribute) views that implement the focus() method,
an associated focus tracker to determine which view is focused.

A simple cycler setup can look like this:

const focusables = new ViewCollection<FocusableView>();
const focusTracker = new FocusTracker();

// Add focusable views to the focus tracker.
focusTracker.add( ... );

Then, the cycler can be used manually:

const cycler = new FocusCycler( { focusables, focusTracker } );

// Will focus the first focusable view in #focusables.
cycler.focusFirst();

// Will log the next focusable item in #focusables.
console.log( cycler.next );

Alternatively, it can work side by side with the KeystrokeHandler:

const keystrokeHandler = new KeystrokeHandler();

// Activate the keystroke handler.
keystrokeHandler.listenTo( sourceOfEvents );

const cycler = new FocusCycler( {
	focusables, focusTracker, keystrokeHandler,
	actions: {
		// When arrowup of arrowleft is detected by the #keystrokeHandler,
		// focusPrevious() will be called on the cycler.
		focusPrevious: [ 'arrowup', 'arrowleft' ],
	}
} );

Check out the "Deep dive into focus tracking" guide to learn more.

See source

Properties

actions : FocusCyclerActions | undefined
readonly
module:ui/focuscycler~FocusCycler#actions
Actions that the cycler can take when a keystroke is pressed. Requires options.keystrokeHandler to be passed and working. When an action is performed, preventDefault and stopPropagation will be called on the event the keystroke fired in the DOM.
```
actions: {
	// Will call #focusPrevious() when arrowleft or arrowup is pressed.
	focusPrevious: [ 'arrowleft', 'arrowup' ],

	// Will call #focusNext() when arrowdown is pressed.
	focusNext: 'arrowdown'
}
```
Copy code
See source (with github icon)
current : null | number
readonly

An index of the view in the focusables which is focused according to focusTracker. Returns null when there is no such view.
See source (with github icon)
first : null | FocusableView
readonly

Returns the first focusable view in focusables. Returns null if there is none.
Note: Hidden views (e.g. with display: none) are ignored.
See source (with github icon)
focusTracker : FocusTracker
readonly

A focus tracker instance that the cycler uses to determine the current focus state in focusables.
See source (with github icon)
focusables : ViewCollection<FocusableView>
readonly

A focusable views collection that the cycler operates on.
See source (with github icon)
keystrokeHandler : KeystrokeHandler | undefined
readonly

An instance of the KeystrokeHandler which can respond to certain keystrokes and cycle the focus.
See source (with github icon)
last : null | FocusableView
readonly

Returns the last focusable view in focusables. Returns null if there is none.
Note: Hidden views (e.g. with display: none) are ignored.
See source (with github icon)
next : null | FocusableView
readonly

Returns the next focusable view in focusables based on current. Returns null if there is none.
Note: Hidden views (e.g. with display: none) are ignored.
See source (with github icon)
previous : null | FocusableView
readonly

Returns the previous focusable view in focusables based on current. Returns null if there is none.
Note: Hidden views (e.g. with display: none) are ignored.
See source (with github icon)

Methods

constructor( options = { [options.actions], options.focusables, options.focusTracker, [options.keystrokeHandler], [options.keystrokeHandlerOptions] } )

Creates an instance of the focus cycler utility.
See source (with github icon)
Parameters
options : object
Configuration options.

Properties

[ options.actions ] : FocusCyclerActions
options.focusables : ViewCollection<FocusableView>
options.focusTracker : FocusTracker
[ options.keystrokeHandler ] : KeystrokeHandler
[ options.keystrokeHandlerOptions ] : KeystrokeHandlerOptions

`chain( chainedFocusCycler ) → void`

module:ui/focuscycler~FocusCycler#chain

Allows for creating continuous focus cycling across multiple focus cyclers and their collections of focusables.

It starts listening to the FocusCyclerForwardCycleEvent and FocusCyclerBackwardCycleEvent events of the chained focus cycler and engages, whenever the user reaches the last (forwards navigation) or first (backwards navigation) focusable view and would normally start over. Instead, the navigation continues on the higher level (flattens).

For instance, for the following nested focus navigation structure, the focus would get stuck the moment the AB gets focused and its focus cycler starts managing it:

   ┌────────────┐   ┌──────────────────────────────────┐   ┌────────────┐
   │ AA         │   │ AB                               │   │ AC         │
   │            │   │                                  │   │            │
   │            │   │    ┌─────┐  ┌─────┐  ┌─────┐     │   │            │
   │            │   │ ┌──► ABA ├──► ABB ├──► ABC ├───┐ │   │            │
   │            ├───► │  └─────┘  └─────┘  └─────┘   │ │   │            │
   │            │   │ │                              │ │   │            │
   │            │   │ │                              │ │   │            │
   │            │   │ └──────────────────────────────┘ │   │            │
   │            │   │                                  │   │            │
   └────────────┘   └──────────────────────────────────┘   └────────────┘

Chaining a focus tracker that manages AA, AB, and AC with the focus tracker that manages ABA, ABB, and ABC creates a seamless navigation experience instead:

   ┌────────────┐   ┌──────────────────────────────────┐   ┌────────────┐
   │ AA         │   │ AB                               │   │ AC         │
   │            │   │                                  │   │            │
   │            │   │    ┌─────┐  ┌─────┐  ┌─────┐     │   │            │
   │            │   │ ┌──► ABA ├──► ABB ├──► ABC ├──┐  │   │            │
┌──►            ├───┼─┘  └─────┘  └─────┘  └─────┘  └──┼───►            ├──┐
│  │            │   │                                  │   │            │  │
│  │            │   │                                  │   │            │  │
│  │            │   │                                  │   │            │  │
│  │            │   │                                  │   │            │  │
│  └────────────┘   └──────────────────────────────────┘   └────────────┘  │
│                                                                          │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

See unchain to reverse the chaining.

See source

Parameters

chainedFocusCycler : FocusCycler

Returns

void

delegate( events ) → EmitterMixinDelegateChain
inherited
module:ui/focuscycler~FocusCycler#delegate
Delegates selected events to another Emitter. For instance:
```
emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
```
Copy code
then eventX is delegated (fired by) emitterB and emitterC along with data:
```
emitterA.fire( 'eventX', data );
```
Copy code
and eventY is delegated (fired by) emitterC along with data:
```
emitterA.fire( 'eventY', data );
```
Copy code
See source (with github icon)
Parameters
events : Array<string>
Event names that will be delegated to another emitter.
Returns
EmitterMixinDelegateChain
fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]
inherited

Fires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.
See source (with github icon)
Type parameters
TEvent : extends BaseEvent
The type describing the event. See BaseEvent.
Parameters
eventOrInfo : GetNameOrEventInfo<TEvent>
The name of the event or EventInfo object if event is delegated.
args : TEvent[ 'args' ]
Additional arguments to be passed to the callbacks.
Returns
GetEventInfo<TEvent>[ 'return' ]
By default the method returns undefined. However, the return value can be changed by listeners through modification of the evt.return's property (the event info is the first param of every callback).
focusFirst() → void

Focuses the first item in focusables.
Note: Hidden views (e.g. with display: none) are ignored.
See source (with github icon)
Returns
void
focusLast() → void

Focuses the last item in focusables.
Note: Hidden views (e.g. with display: none) are ignored.
See source (with github icon)
Returns
void
focusNext() → void

Focuses the next item in focusables.
Note: Hidden views (e.g. with display: none) are ignored.
See source (with github icon)
Returns
void
focusPrevious() → void

Focuses the previous item in focusables.
Note: Hidden views (e.g. with display: none) are ignored.
See source (with github icon)
Returns
void
listenTo( emitter, event, callback, [ options ] ) → void
inherited
module:ui/focuscycler~FocusCycler#listenTo:BASE_EMITTER
Registers a callback function to be executed when an event is fired in a specific (emitter) object.
Events can be grouped in namespaces using :. When namespaced event is fired, it additionally fires all callbacks for that namespace.
```
// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );
```
Copy code
An event callback can stop the event and set the return value of the fire method.
See source (with github icon)
Type parameters
TEvent : extends BaseEvent
The type describing the event. See BaseEvent.
Parameters
emitter : Emitter
The object that fires the event.
event : TEvent[ 'name' ]
The name of the event.
callback : GetCallback<TEvent>
The function to be called on event.
[ options ] : GetCallbackOptions<TEvent>
Additional options.
Returns
void
off( event, callback ) → void
inherited

Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).
See source (with github icon)
Parameters
event : string
The name of the event.
callback : Function
The function to stop being called.
Returns
void
on( event, callback, [ options ] ) → void
inherited

Registers a callback function to be executed when an event is fired.
Shorthand for this.listenTo( this, event, callback, options ) (it makes the emitter listen on itself).
See source (with github icon)
Type parameters
TEvent : extends BaseEvent
The type descibing the event. See BaseEvent.
Parameters
event : TEvent[ 'name' ]
The name of the event.
callback : GetCallback<TEvent>
The function to be called on event.
[ options ] : GetCallbackOptions<TEvent>
Additional options.
Returns
void
once( event, callback, [ options ] ) → void
inherited

Registers a callback function to be executed on the next time the event is fired only. This is similar to calling on followed by off in the callback.
See source (with github icon)
Type parameters
TEvent : extends BaseEvent
The type descibing the event. See BaseEvent.
Parameters
event : TEvent[ 'name' ]
The name of the event.
callback : GetCallback<TEvent>
The function to be called on event.
[ options ] : GetCallbackOptions<TEvent>
Additional options.
Returns
void
stopDelegating( [ event ], [ emitter ] ) → void
inherited
module:ui/focuscycler~FocusCycler#stopDelegating
Stops delegating events. It can be used at different levels:
- To stop delegating all events.
- To stop delegating a specific event to all emitters.
- To stop delegating a specific event to a specific emitter.
See source (with github icon)
Parameters
[ event ] : string
The name of the event to stop delegating. If omitted, stops it all delegations.
[ emitter ] : Emitter
(requires event) The object to stop delegating a particular event to. If omitted, stops delegation of event to all emitters.
Returns
void
stopListening( [ emitter ], [ event ], [ callback ] ) → void
inherited
module:ui/focuscycler~FocusCycler#stopListening:BASE_STOP
Stops listening for events. It can be used at different levels:
- To stop listening to a specific callback.
- To stop listening to a specific event.
- To stop listening to all events fired by a specific object.
- To stop listening to all events fired by all objects.
See source (with github icon)
Parameters
[ emitter ] : Emitter
The object to stop listening to. If omitted, stops it for all objects.
[ event ] : string
(Requires the emitter) The name of the event to stop listening to. If omitted, stops it for all events from emitter.
[ callback ] : Function
(Requires the event) The function to be removed from the call list for the given event.
Returns
void
unchain( otherFocusCycler ) → void

Reverses a chaining made by chain.
See source (with github icon)
Parameters
otherFocusCycler : FocusCycler
Returns
void
_focus( view, direction ) → void
private

Focuses the given view if it exists.
See source (with github icon)
Parameters
view : null | FocusableView
The view to be focused
direction : 1 | 1
The direction of the focus if the view has focusable children.
Returns
void
_getDomFocusableItem( step ) → null | FocusableView
private

Returns the next or previous focusable view in focusables with respect to current.
See source (with github icon)
Parameters
step : 1 | 1
Either 1 for checking forward from current or -1 for checking backwards.
Returns
null | FocusableView

FocusCycler

Properties

actions : FocusCyclerActions | undefinedreadonly

current : null | numberreadonly

first : null | FocusableViewreadonly

focusTracker : FocusTrackerreadonly

focusables : ViewCollection<FocusableView>readonly

keystrokeHandler : KeystrokeHandler | undefinedreadonly

last : null | FocusableViewreadonly

next : null | FocusableViewreadonly

previous : null | FocusableViewreadonly

Methods

constructor( options = { [options.actions], options.focusables, options.focusTracker, [options.keystrokeHandler], [options.keystrokeHandlerOptions] } )

Parameters

chain( chainedFocusCycler ) → void

Parameters

Returns

delegate( events ) → EmitterMixinDelegateChaininherited

Parameters

Returns

fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]inherited

Type parameters

Parameters

Returns

focusFirst() → void

Returns

focusLast() → void

Returns

focusNext() → void

Returns

focusPrevious() → void

Returns

listenTo( emitter, event, callback, [ options ] ) → voidinherited

Type parameters

Parameters

Returns

off( event, callback ) → voidinherited

Parameters

Returns

on( event, callback, [ options ] ) → voidinherited

Type parameters

Parameters

Returns

once( event, callback, [ options ] ) → voidinherited

Type parameters

Parameters

Returns

stopDelegating( [ event ], [ emitter ] ) → voidinherited

Parameters

Returns

stopListening( [ emitter ], [ event ], [ callback ] ) → voidinherited

Parameters

Returns

unchain( otherFocusCycler ) → void

Parameters

Returns

_focus( view, direction ) → void Lock iconprivate

Parameters

Returns

_getDomFocusableItem( step ) → null | FocusableView Lock iconprivate

Parameters

Returns

Events

backwardCycle( eventInfo )

Parameters

forwardCycle( eventInfo )

Parameters

`actions : FocusCyclerActions | undefined`
readonly

`current : null | number`
readonly

`first : null | FocusableView`
readonly

`focusTracker : FocusTracker`
readonly

`focusables : ViewCollection<FocusableView>`
readonly

`keystrokeHandler : KeystrokeHandler | undefined`
readonly

`last : null | FocusableView`
readonly

`next : null | FocusableView`
readonly

`previous : null | FocusableView`
readonly

`constructor( options = { [options.actions], options.focusables, options.focusTracker, [options.keystrokeHandler], [options.keystrokeHandlerOptions] } )`

`chain( chainedFocusCycler ) → void`

`delegate( events ) → EmitterMixinDelegateChain`
inherited

`fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]`
inherited

`focusFirst() → void`

`focusLast() → void`

`focusNext() → void`

`focusPrevious() → void`

`listenTo( emitter, event, callback, [ options ] ) → void`
inherited

`off( event, callback ) → void`
inherited

`on( event, callback, [ options ] ) → void`
inherited

`once( event, callback, [ options ] ) → void`
inherited

`stopDelegating( [ event ], [ emitter ] ) → void`
inherited

`stopListening( [ emitter ], [ event ], [ callback ] ) → void`
inherited

`unchain( otherFocusCycler ) → void`

`_focus( view, direction ) → void`
private

`_getDomFocusableItem( step ) → null | FocusableView`
private

`backwardCycle( eventInfo )`

`forwardCycle( eventInfo )`