A _Container with keyboard navigation of its children.
Provides normalized keyboard and focusing code for Container widgets. To use this mixin, call connectKeyNavHandlers() in postCreate(). Also, child widgets must implement a focus() method.
See the dijit/_KeyNavContainer 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.
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 |
|
Get the next or previous widget sibling of child
| Parameter | Type | Description |
|---|---|---|
| child | dijit/_WidgetBase | |
| dir | int | if 1, get the next sibling if -1, get the previous sibling |
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 |
Setup for each child widget.
Sets tabIndex=-1 on each child, so that the tab key will leave the container rather than visiting each child.
Note: if you add children by a different method than addChild(), then need to call this manually or at least make sure the child's tabIndex is -1.
Note: see also _LayoutWidget.setupChild(), which is also called for each child widget.
| Parameter | Type | Description |
|---|---|---|
| widget | dijit/_WidgetBase |
| Parameter | Type | Description |
|---|---|---|
| widget | dijit/_WidgetBase | |
| insertIndex | int |
Optional
|
Deprecated. You can call this in postCreate() to attach the keyboard handlers to the container, but the preferred method is to override _onLeftArrow() and _onRightArrow(), or _onUpArrow() and _onDownArrow(), to call focusPrev() and focusNext().
| Parameter | Type | Description |
|---|---|---|
| prevKeyCodes | dojo/keys | Key codes for navigating to the previous child. |
| nextKeyCodes | dojo/keys | Key codes for navigating to the next child. |
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 |
Focus the last focusable node in the previous widget (ex: go to the ComboButton icon section rather than button section)
Gets the index of the child in this container or -1 if not found
| Parameter | Type | Description |
|---|---|---|
| child | dijit/_WidgetBase |
Returns true if widget has child widgets, i.e. if this.containerNode contains widgets.
Removes the passed widget instance from this widget but does not destroy it. You can also pass in an integer indicating the index within the container to remove (ie, removeChild(5) removes the sixth widget).
| Parameter | Type | Description |
|---|---|---|
| widget | Widget | int |
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 |