Delegate for the navigation between DOM nodes with the keyboard.
The ItemNavigation
provides keyboard and mouse navigation between DOM nodes representing items. This means that controls rendering a list of items can attach this delegate to get a common keyboard and mouse support to navigate between these items. It is possible to navigate between the items via the arrow keys. If needed, paging using the Page Up and Page Down keys is possible. (To activate call setPageSize
with a value > 0.) HOME and END keys are also supported. Focusing an item via mouse also is also supported. For mouse navigation, the mousedown
event is used.
As the ItemNavigation
works with DOM nodes, the items and the control area must be provided as DOM references. There is one root DOM reference (set via setRootDomRef
). All item DOM references (set via setItemDomRefs
) must be places somewhere inside of this root DOM reference. Only focusable items are used for the navigation, meaning disabled items or separator items are just ignored by navigating through the items. In some cases however, it makes sense to put the non-focusable items in the array of the DOM references to keep the indexes stable or like in the calling control. Hint: To make a DOM reference focusable a tabindex
of -1 can be set.
Note After re-rendering of the control or changing the DOM nodes of the control, the DOM references of the ItemNavigation
must be updated. Then the same item (corresponding to the index) will get the focus.
The ItemNavigation
adjusts the tabindex
of all DOM references relating to the current focused item. So if the control containing the items gets the focus (e.g. via tab navigation), it is always the focused items which will be focused.
Note: If the ItemNavigation
is nested in another ItemNavigation
(e.g. SegmentedButton
in Toolbar
), the RootDomRef
will always have tabindex
-1.
Per default the ItemNavigation
cycles over the items. It navigates again to the first item if the Arrow Down or Arrow Right key is pressed while the last item has the focus. It navigates to the last item if arrow up or arrow left is pressed while the first item has the focus. If you want to stop the navigation at the first and last item, call the setCycling
method with a value of false
.
It is possible to have multiple columns in the item navigation. If multiple columns are used, the keyboard navigation changes. The Arrow Right and Arrow Left keys will take the user to the next or previous item, and the Arrow Up and Arrow Down keys will navigate the same way but in a vertical direction.
The ItemNavigation
also allows setting a selected index that is used to identify the selected item. Initially, if no other focus is set, the selected item will be the focused one. Note that navigating through the items will not change the selected item, only the focus. (For example a radio group has one selected item.)
Creates an ItemNavigation
delegate that can be attached to controls requiring capabilities for keyboard navigation between items.
new sap.ui.core.delegate.ItemNavigation(oDomRef, aItemDomRefs, bNotInTabChain?)
Param | Type | Default Value | Description |
---|---|---|---|
oDomRef | Element | The root DOM reference that includes all items |
|
aItemDomRefs | Element[] | Array of DOM references representing the items for the navigation |
|
bNotInTabChain? | boolean | false | Whether the selected element should be in the tab chain or not |
Event | Description |
---|---|
afterFocus |
The 'afterFocus' event is fired after the actual item is focused. The control can register to this event and react on the focus change. |
beforeFocus |
The 'beforeFocus' event is fired before the actual item is focused. |
borderReached |
The 'borderReached' event is fired if the border of the items is reached and no cycling is used, meaning an application can react on this. For example if the first item is focused and the Arrow Left key is pressed. |
focusAgain |
The 'focusAgain' event is fired if the current focused item is focused again (e.g. click again on focused item.) |
focusLeave |
The 'focusLeave' event fired if the focus is set outside the control handled by the |
The 'afterFocus' event is fired after the actual item is focused. The control can register to this event and react on the focus change.
Param | Type | Description |
---|---|---|
index | int |
Index of the item |
event | jQuery.Event |
Event that leads to the focus change |
The 'beforeFocus' event is fired before the actual item is focused.
Param | Type | Description |
---|---|---|
index | int |
Index of the item |
event | jQuery.Event |
Event that leads to the focus change |
The 'borderReached' event is fired if the border of the items is reached and no cycling is used, meaning an application can react on this.
For example if the first item is focused and the Arrow Left key is pressed.
Param | Type | Description |
---|---|---|
index | int |
Index of the item |
event | jQuery.Event |
Event that leads to the focus change |
Method | Description |
---|---|
sap.ui.core.delegate.ItemNavigation.extend |
Creates a new subclass of class sap.ui.core.delegate.ItemNavigation with name
|
getDisabledModifiers |
Returns disabled modifiers These modifiers will not be handled by the |
getItemDomRefs |
Returns the array of item DOM references |
sap.ui.core.delegate.ItemNavigation.getMetadata |
Returns a metadata object for class sap.ui.core.delegate.ItemNavigation. |
getRootDomRef |
Returns the root DOM reference surrounding the items |
hasDisabledModifier |
Check whether given event has disabled modifier or not |
setColumns |
Sets whether the items are displayed in columns. If columns are used, the Arrow Up and Arrow Down keys navigate to the next or previous item of the column. If the first or last item of the column is reached, the next focused item is then in the next or previous column. |
setCycling |
Sets whether the If cycling is disabled the navigation stops at the first and last item, if the corresponding arrow keys are used. |
setDisabledModifiers |
Sets the disabled modifiers These modifiers will not be handled by the
Example: Disable shift + up handling of the
|
setHomeEndColumnMode |
Sets behavior of HOME and END keys if columns are used. |
setItemDomRefs |
Sets the item DOM references as an array for the items |
setPageSize |
Sets the page size of the item navigation to allow Page Up and Page Down keys. |
setRootDomRef |
Sets the root DOM reference surrounding the items |
setSelectedIndex |
Sets the selected index if the used control supports selection. |
setTableMode |
Sets whether the |
Returns disabled modifiers These modifiers will not be handled by the ItemNavigation
Param | Type | DefaultValue | Description |
---|---|---|---|
oDisabledModifiers | object |
Object that includes event type with disabled keys as an array |
Check whether given event has disabled modifier or not
Param | Type | DefaultValue | Description |
---|---|---|---|
oEvent | jQuery.Event |
jQuery event |
Sets whether the items are displayed in columns.
If columns are used, the Arrow Up and Arrow Down keys navigate to the next or previous item of the column. If the first or last item of the column is reached, the next focused item is then in the next or previous column.
Param | Type | DefaultValue | Description |
---|---|---|---|
iColumns | int |
Count of columns for the table mode or cycling mode |
|
bNoColumnChange | boolean |
Forbids jumping to an other column with Arrow Up and Arrow Down keys |
Sets whether the ItemNavigation
should cycle through the items.
If cycling is disabled the navigation stops at the first and last item, if the corresponding arrow keys are used.
Param | Type | DefaultValue | Description |
---|---|---|---|
bCycling | boolean |
Set to true if cycling should be done, else false |
Sets the disabled modifiers These modifiers will not be handled by the ItemNavigation
Example: Disable shift + up handling of the ItemNavigation
oItemNavigation.setDisabledModifiers({
sapnext : ["shift"]
});
Possible keys are : "shift", "alt", "ctrl", "meta"
Possible events are : "sapnext", "sapprevious", "saphome", "sapend"
Param | Type | DefaultValue | Description |
---|---|---|---|
oDisabledModifiers | Object |
Object that includes event type with disabled keys as an array |
Sets behavior of HOME and END keys if columns are used.
Param | Type | DefaultValue | Description |
---|---|---|---|
bStayInRow | boolean |
HOME -> go to first item in row; END -> go to last item in row |
|
bCtrlEnabled | boolean |
HOME/END with CTRL -> go to first/last item of all |
Sets the item DOM references as an array for the items
Param | Type | DefaultValue | Description |
---|---|---|---|
aItemDomRefs | Element[] |
Array of DOM references or DOM node list object, representing the items |
Sets the page size of the item navigation to allow Page Up and Page Down keys.
Param | Type | DefaultValue | Description |
---|---|---|---|
iPageSize | int |
The page size, needs to be at least 1 |
Sets the root DOM reference surrounding the items
Param | Type | DefaultValue | Description |
---|---|---|---|
oDomRef | object |
Root DOM reference |
Sets the selected index if the used control supports selection.
Param | Type | DefaultValue | Description |
---|---|---|---|
iIndex | int |
Index of the first selected item |
Sets whether the ItemNavigation
should use the table mode to navigate through the items (navigation in a grid).
Param | Type | DefaultValue | Description |
---|---|---|---|
bTableMode | boolean |
Set to true if table mode should be used, else false |
|
bTableList | boolean |
This sets a different behavior for table mode. In this mode we keep using table navigation but there are some differences. e.g.
|