Navigator

A helper class which allows keyboard navigation within the target element.

Configs

activateOnMouseover: Boolean

Configure as true to activate items on mouseover. This is used by the Combo field when using a List as its dropdown.

activeItem: HTMLElement

The currently focused element within the target.

allowCtrlKey: Boolean= false

Configure as true to also navigate when the CTRL modifier key is used along with navigation keys.

allowShiftKey: Boolean= false

Configure as true to also navigate when the SHIFT modifier key is used along with navigation keys.

columnCount: Number

The number of columns if the navigable items are in a flexbox or grid layout.

This is used to determine the action taken when using UP and DOWN arrow keys.

This is calculated automatically from the grid-template-columns style of the item container if possible. If using a flexbox layout, and there is a regular number of columns on every row, specify the number of columns there will be in each row.

disabled: Boolean

Configure as, or set to true to disable the processing of keys.

focusCls: String= b-active

A CSS class name to add to focused elements.

itemSelector: String

A query selector which identifies descendant elements within the target which are navigable.

itemsTabbable: Boolean

If the items in the owning widget are naturally tabbable, then the Navigator does not need to listen for navigation keys and move focus. It just reacts to natural focus movement.

keyEventTarget: HTMLElement

The element which provides key events for navigation. Optional. Defaults to the target element.

keys: Object<String, (String|function())>

An object containing key definitions keyed by the key name eg:

 keys : {
     "CTRL+Space" : 'onCtrlSpace',
     Enter        : 'onEnterKey'
 }

The ownerCmp is used as the this reference and to resolve string method names.

The following arguments are passed to the handling method:

keyEvent : The key event.
navigator : This Navigator instance.
activeItem : The currently focused element.

Modified key names must be created prepending one or more 'CTRL+', 'SHIFT+', 'ALT+' in that order, for example "CTRL+SHIFT+Enter" : 'showMenu'

ownerCmp: Widget

The owning Widget which is using this Navigator.

processEvent: String | function

An optional key event processor which may preprocess the key event. Returning null prevents processing of the event.

Parameter	Type	Description
`event`	KeyboardEvent

Returns: Boolean | null

target: HTMLElement

The encapsulating element in which navigation takes place.

Functions

getAdjacent

Returns the next or previous navigable element starting from the passed from element, navigating in the passed direction.

Parameter	Type	Description
`from`	HTMLElement	The start point. Defaults to the current activeItem
`direction`	Number	The direction. -1 for backwards, else forwards.

Events

navigate

Fired when a user gesture causes the active item to change or become null.

// Adding a listener using the "on" method
navigator.on('navigate', ({ event, item, oldItem }) => {

});

Parameter	Type	Description
`event`	Event	The browser event which instigated navigation. May be a click or key or focus move event.
`item`	HTMLElement	The newly active item, or `null` if focus moved out.
`oldItem`	HTMLElement	The previously active item, or `null` if focus is moving in.

Event handlers

onNavigate

Called when a user gesture causes the active item to change or become null.

new Navigator({
    onNavigate({ event, item, oldItem }) {

    }
});

Parameter	Type	Description
`event`	Event	The browser event which instigated navigation. May be a click or key or focus move event.
`item`	HTMLElement	The newly active item, or `null` if focus moved out.
`oldItem`	HTMLElement	The previously active item, or `null` if focus is moving in.