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

Methods

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

Parameters

chain( chainedFocusCycler ) → void

Parameters

Returns

delegate( events ) → EmitterMixinDelegateChain inherited

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 ] ) → void inherited

Type parameters

Parameters

Returns

off( event, callback ) → void inherited

Parameters

Returns

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

Type parameters

Parameters

Returns

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

Type parameters

Parameters

Returns

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

Parameters

Returns

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

Parameters

Returns

unchain( otherFocusCycler ) → void

Parameters

Returns

_focus( view, direction ) → void Lock icon private

Parameters

Returns

_getDomFocusableItem( step ) → null | FocusableView Lock icon private

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 )`