ItemNavigation

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 Summary

new sap.ui.core.delegate.ItemNavigation(oDomRef, aItemDomRefs, bNotInTabChain?)Creates an ItemNavigation delegate that can be attached to controls requiring capabilities for keyboard navigation between items.

Event Summary

afterFocus(index, event)The 'afterFocus' event is fired after the actual item is focused.

beforeFocus(index, event)The 'beforeFocus' event is fired before the actual item is focused.

borderReached(index, event)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.

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

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

Method Summary

sap.ui.core.delegate.ItemNavigation.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.ui.core.delegate.ItemNavigation with name sClassName and enriches it with the information contained in oClassInfo.

sap.ui.core.delegate.ItemNavigation.getMetadata()Returns a metadata object for class sap.ui.core.delegate.ItemNavigation.

getDisabledModifiers(oDisabledModifiers)Returns disabled modifiers These modifiers will not be handled by the ItemNavigation

getItemDomRefs()Returns the array of item DOM references

getRootDomRef()Returns the root DOM reference surrounding the items

hasDisabledModifier(oEvent)Check whether given event has disabled modifier or not

setColumns(iColumns, bNoColumnChange)Sets whether the items are displayed in columns.

setCycling(bCycling)Sets whether the ItemNavigation should cycle through the items.

setDisabledModifiers(oDisabledModifiers)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(bStayInRow, bCtrlEnabled)Sets behavior of HOME and END keys if columns are used.

setItemDomRefs(aItemDomRefs)Sets the item DOM references as an array for the items

setPageSize(iPageSize)Sets the page size of the item navigation to allow Page Up and Page Down keys.

setRootDomRef(oDomRef)Sets the root DOM reference surrounding the items

setSelectedIndex(iIndex)Sets the selected index if the used control supports selection.

setTableMode(bTableMode, bTableList?)Sets whether the ItemNavigation should use the table mode to navigate through the items (navigation in a grid).

Methods borrowed from class sap.ui.base.EventProvider

attachEvent, attachEventOnce, detachEvent, fireEvent, getEventingParent, hasListeners, toString

Methods borrowed from class sap.ui.base.Object

getInterface, getMetadata

Constructor Detail

new sap.ui.core.delegate.ItemNavigation(oDomRef, aItemDomRefs, bNotInTabChain?)

Creates an ItemNavigation delegate that can be attached to controls requiring capabilities for keyboard navigation between items.

Parameters:

{Element}	oDomRef	The root DOM reference that includes all items
{Element[]}	aItemDomRefs	Array of DOM references representing the items for the navigation
{boolean}	bNotInTabChain?	Whether the selected element should be in the tab chain or not

Event Detail

afterFocus(index, event)

The 'afterFocus' event is fired after the actual item is focused. The control can register to this event and react on the focus change.

Parameters:

{int}	index	Index of the item
{jQuery.Event}	event	Event that leads to the focus change

beforeFocus(index, event)

The 'beforeFocus' event is fired before the actual item is focused.

Parameters:

{int}	index	Index of the item
{jQuery.Event}	event	Event that leads to the focus change

borderReached(index, event)

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.

Parameters:

{int}	index	Index of the item
{jQuery.Event}	event	Event that leads to the focus change

focusAgain(index, event)

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

Parameters:

{int}	index	Index of the item
{jQuery.Event}	event	Event that leads to the focus change

focusLeave(index, event)

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

Parameters:

{int}	index	Index of the item
{jQuery.Event}	event	Event that leads to the focus change

Method Detail

sap.ui.core.delegate.ItemNavigation.extend(sClassName, oClassInfo?, FNMetaImpl?): function

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.

Parameters:

{string}	sClassName	Name of the class being created
{object}	oClassInfo?	Object literal with information about the class
{function}	FNMetaImpl?	Constructor function for the metadata object; if not given, it defaults to `sap.ui.core.ElementMetadata`

Returns:

{function}

Created class / constructor function

sap.ui.core.delegate.ItemNavigation.getMetadata(): sap.ui.base.Metadata

Returns a metadata object for class sap.ui.core.delegate.ItemNavigation.

Returns:

{sap.ui.base.Metadata}

Metadata object describing this class

getDisabledModifiers(oDisabledModifiers): object

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

Parameters:

{object}

oDisabledModifiers

Object that includes event type with disabled keys as an array

Returns:

{object}

Object that includes event type with disabled keys as an array

getItemDomRefs(): Element[]

Returns the array of item DOM references

Returns:

{Element[]}

Array of item DOM references

getRootDomRef(): Element

Returns the root DOM reference surrounding the items

Returns:

{Element}

Root DOM reference

hasDisabledModifier(oEvent): Boolean

Check whether given event has disabled modifier or not

Parameters:

{jQuery.Event}

oEvent

jQuery event

Returns:

{Boolean}

Flag if disabled modifiers are set

setColumns(iColumns, bNoColumnChange): sap.ui.core.delegate.ItemNavigation

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.

Parameters:

{int}	iColumns	Count of columns for the table mode or cycling mode
{boolean}	bNoColumnChange	Forbids jumping to an other column with Arrow Up and Arrow Down keys

Returns:

{sap.ui.core.delegate.ItemNavigation} this to allow method chaining

setCycling(bCycling): sap.ui.core.delegate.ItemNavigation

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.

Parameters:

{boolean}

bCycling

Set to true if cycling should be done, else false

Returns:

{sap.ui.core.delegate.ItemNavigation} this to allow method chaining

setDisabledModifiers(oDisabledModifiers): sap.ui.core.delegate.ItemNavigation

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"

Parameters:

{Object}

oDisabledModifiers

Object that includes event type with disabled keys as an array

Returns:

{sap.ui.core.delegate.ItemNavigation} this to allow method chaining

setHomeEndColumnMode(bStayInRow, bCtrlEnabled): sap.ui.core.delegate.ItemNavigation

Sets behavior of HOME and END keys if columns are used.

Parameters:

{boolean}	bStayInRow	HOME -> go to first item in row; END -> go to last item in row
{boolean}	bCtrlEnabled	HOME/END with CTRL -> go to first/last item of all

Returns:

{sap.ui.core.delegate.ItemNavigation} this to allow method chaining

setItemDomRefs(aItemDomRefs): sap.ui.core.delegate.ItemNavigation

Sets the item DOM references as an array for the items

Parameters:

{Element[]}

aItemDomRefs

Array of DOM references representing the items

Returns:

{sap.ui.core.delegate.ItemNavigation} this to allow method chaining

setPageSize(iPageSize): sap.ui.core.delegate.ItemNavigation

Sets the page size of the item navigation to allow Page Up and Page Down keys.

Parameters:

{int}

iPageSize

The page size, needs to be at least 1

Returns:

{sap.ui.core.delegate.ItemNavigation} this to allow method chaining

setRootDomRef(oDomRef): sap.ui.core.delegate.ItemNavigation

Sets the root DOM reference surrounding the items

Parameters:

{object}

oDomRef

Root DOM reference

Returns:

{sap.ui.core.delegate.ItemNavigation} this to allow method chaining

setSelectedIndex(iIndex): sap.ui.core.delegate.ItemNavigation

Sets the selected index if the used control supports selection.

Parameters:

{int}

iIndex

Index of the first selected item

Returns:

{sap.ui.core.delegate.ItemNavigation} this to allow method chaining

setTableMode(bTableMode, bTableList?): sap.ui.core.delegate.ItemNavigation

Sets whether the ItemNavigation should use the table mode to navigate through the items (navigation in a grid).

Parameters:

{boolean}	bTableMode	Set to true if table mode should be used, else false
{boolean}	bTableList?	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

Returns:

{sap.ui.core.delegate.ItemNavigation} this to allow method chaining