class sap.ui.core.delegate.ItemNavigation

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/core/delegate/ItemNavigation
Application Component: CA-UI5-COR

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


Constructor

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


Events Overview

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

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.

Param Type Description
index int

Index of the item

event jQuery.Event

Event that leads to the focus change

beforeFocus

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

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.

Param Type Description
index int

Index of the item

event jQuery.Event

Event that leads to the focus change

focusAgain

The 'focusAgain' event is fired if the current focused item is focused again (e.g. click again on focused item.)

Param Type Description
index int

Index of the item

event jQuery.Event

Event that leads to the focus change

focusLeave

The 'focusLeave' event fired if the focus is set outside the control handled by the ItemNavigation.

Param Type Description
index int

Index of the item

event jQuery.Event

Event that leads to the focus change


Methods Overview

Method Description
sap.ui.core.delegate.ItemNavigation.extend

Creates a new subclass of class sap.ui.core.delegate.ItemNavigation with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.base.EventProvider.extend.

getDisabledModifiers

Returns disabled modifiers These modifiers will not be handled by the ItemNavigation

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

setDisabledModifiers

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"

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 ItemNavigation should use the table mode to navigate through the items (navigation in a grid).

sap.ui.core.delegate.ItemNavigation.extend

Creates a new subclass of class sap.ui.core.delegate.ItemNavigation with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.base.EventProvider.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

getDisabledModifiers

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

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

Param Type DefaultValue Description
oEvent jQuery.Event

jQuery event

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.

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

setCycling

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

setDisabledModifiers

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

setHomeEndColumnMode

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

setItemDomRefs

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

setPageSize

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

setRootDomRef

Sets the root DOM reference surrounding the items

Param Type DefaultValue Description
oDomRef object

Root DOM reference

setSelectedIndex

Sets the selected index if the used control supports selection.

Param Type DefaultValue Description
iIndex int

Index of the first selected item

setTableMode

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.

  • Page-up moves focus to the first row, not to the first cell like in table mode
  • Page-down moves focus to the last row, not to the last cell like in table mode