A mixin to allow arrow key and letter key navigation of child or descendant widgets. It can be used by dijit/_Container based widgets with a flat list of children, or more complex widgets like dijit/Tree.
To use this mixin, the subclass must:
- Implement _getNext(), _getFirst(), _getLast(), _onLeftArrow(), _onRightArrow() _onDownArrow(), _onUpArrow() methods to handle home/end/left/right/up/down keystrokes. Next and previous in this context refer to a linear ordering of the descendants used by letter key search. - Set all descendants' initial tabIndex to "-1"; both initial descendants and any descendants added later, by for example addChild() - Define childSelector to a function or string that identifies focusable descendant widgets
Also, child widgets must implement a focus() method.
See the dijit/_KeyNavMixin reference documentation for more information.
Hash mapping key code (arrow keys and home/end key) to functions to handle those keys. Usually not used directly, as subclasses can instead override _onLeftArrow() etc.
Selector (passed to on.selector()) used to identify what to treat as a child widget. Used to monitor focus events and set this.focusedChild. Must be set by implementing class. If this is a string (ex: "> *") then the implementing class must require dojo/query.
The currently focused child widget, or null if there isn't one
If multiple characters are typed where each keystroke happens within multiCharSearchDuration of the previous keystroke, search for nodes matching all the keystrokes.
For example, typing "ab" will search for entries starting with "ab" unless the delay between "a" and "b" is greater than multiCharSearchDuration.
Tab index of the container; same as HTML tabIndex attribute. Note then when user tabs into the container, focus is immediately moved to the first item in the container.
Returns the next descendant, compared to "child".
| Parameter | Type | Description |
|---|---|---|
| child | Widget | The current widget |
| dir | Integer |
|
Returns the next or previous focusable descendant, compared to "child". Implements and extends _KeyNavMixin._getNextFocusableChild() for a _Container.
| Parameter | Type | Description |
|---|---|---|
| child | Widget | The current widget |
| dir | Integer |
|
Perform a search of the widget's options based on the user's keyboard activity
Called on keypress (and sometimes keydown), searches through this widget's children looking for items that match the user's typed search string. Multiple characters typed within 1 sec of each other are combined for multicharacter searching.
| Parameter | Type | Description |
|---|---|---|
| evt | Event | |
| keyChar | String |
Compares the searchString to the widget's text label, returning:
* -1: a high priority match and stop searching * 0: not a match * 1: a match but keep looking for a higher priority match
| Parameter | Type | Description |
|---|---|---|
| item | dijit/_WidgetBase | |
| searchString | String |
Focus specified child widget.
| Parameter | Type | Description |
|---|---|---|
| widget | dijit/_WidgetBase | Reference to container's child widget |
| last | Boolean | If true and if widget has multiple focusable nodes, focus the last one instead of the first one |
Called when focus leaves a child widget to go to a sibling widget. Used to be used by MenuBase.js (remove for 2.0)
| Parameter | Type | Description |
|---|---|---|
| widget | dijit/_WidgetBase |
Called when a child widget gets focus, either by user clicking it, or programatically by arrow key handling code.
It marks that the current node is the selected one, and the previously selected node no longer is.
| Parameter | Type | Description |
|---|---|---|
| child | dijit/_WidgetBase |
Handler for when the container itself gets focus.
Initially the container itself has a tabIndex, but when it gets focus, switch focus to first child.
TODO for 2.0 (or earlier): Instead of having the container tabbable, always maintain a single child widget as tabbable, Requires code in startup(), addChild(), and removeChild(). That would avoid various issues like #17347.
| Parameter | Type | Description |
|---|---|---|
| evt | undefined |
When a key is pressed, if it's an arrow key etc. then it's handled here.
| Parameter | Type | Description |
|---|---|---|
| evt | undefined |
When a printable key is pressed, it's handled here, searching by letter.
| Parameter | Type | Description |
|---|---|---|
| evt | undefined |
Called on down arrow key. Should go to the next child in vertical container widgets like Menu.
Called on left arrow key, or right arrow key if widget is in RTL mode. Should go back to the previous child in horizontal container widgets like Toolbar.
Called on right arrow key, or left arrow key if widget is in RTL mode. Should go to the next child in horizontal container widgets like Toolbar.
Called on up arrow key. Should go to the previous child in vertical container widgets like Menu.
When a key is pressed that matches a child item, this method is called so that a widget can take appropriate action is necessary.
| Parameter | Type | Description |
|---|---|---|
| item | dijit/_WidgetBase | |
| evt | Event | |
| searchString | String | |
| numMatches | Number |