Provides enhanced navigation capabilities and is the parent control of NavigationItem. It is displayed in the form of a horizontal line with switching markers depending on the currently selected item. The size of an item which is currently chosen by the user is enlarged. In the case that a large number of items are defined for the bar, this is made transparent to the user by showing symbols for scrolling options (forwards and backwards) to see the next or previous items.
Constructor for a new NavigationBar.
Accepts an object literal mSettings
that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.
new sap.ui.ux3.NavigationBar(sId?, mSettings?)
Param | Type | Default Value | Description |
---|---|---|---|
sId? | string | id for the new control, generated automatically if no id is given |
|
mSettings? | object | initial settings for the new control |
Name | Type | Default Value | Description |
---|---|---|---|
overflowItemsToUpperCase | boolean | false | Sets the appearance of the menu items in the overflow menu to uppercase |
toplevelVariant | boolean | false | Defines whether the navigation bar shall have top-level appearance Visibility: public |
Default Aggregation: items
Name | Cardinality | Type | Description |
---|---|---|---|
items (default) | 0..n | sap.ui.ux3.NavigationItem |
If the navigation items need to have a different parent than the NavigationBar, alternatively the associatedItems association can be used. The NavigationBar follows the approach to use the items aggregation. If this aggregation is empty, associatedItems is used. |
overflowMenu | 0..1 | sap.ui.commons.Menu |
Hidden aggregation for the overflow menu if applicable |
Name | Cardinality | Type | Description |
---|---|---|---|
associatedItems | 0..n | sap.ui.ux3.NavigationItem |
This association is ignored as long as the items aggregation is used; and supposed to be used alternatively when the items should be aggregated by other entities. |
selectedItem | 0..1 | sap.ui.ux3.NavigationItem |
The selected NavigationItem. |
Event | Description |
---|---|
select |
Event is fired when an item is selected by the user Listeners may prevent the default action of this event by calling the |
Event is fired when an item is selected by the user
Listeners may prevent the default action of this event by calling the preventDefault
method on the event object.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
itemId | string |
The ID of the newly selected NavigationItem. |
item | sap.ui.ux3.NavigationItem |
The newly selected NavigationItem. |
Method | Description |
---|---|
addAssociatedItem |
Adds some associatedItem into the association associatedItems. |
addItem |
Adds some item to the aggregation items. |
attachSelect |
Attaches event handler When called, the context of the event handler (its Event is fired when an item is selected by the user |
destroyItems |
Destroys all the items in the aggregation items. |
detachSelect |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.ui.ux3.NavigationBar.extend |
Creates a new subclass of class sap.ui.ux3.NavigationBar with name
|
fireSelect |
Fires event select to attached listeners. Listeners may prevent the default action of this event by calling the |
getAssociatedItems |
Returns array of IDs of the elements which are the current targets of the association associatedItems. |
getItems |
Gets content of aggregation items. If the navigation items need to have a different parent than the NavigationBar, alternatively the associatedItems association can be used. The NavigationBar follows the approach to use the items aggregation. If this aggregation is empty, associatedItems is used. |
sap.ui.ux3.NavigationBar.getMetadata |
Returns a metadata object for class sap.ui.ux3.NavigationBar. |
getOverflowItemsToUpperCase |
Gets current value of property overflowItemsToUpperCase. Sets the appearance of the menu items in the overflow menu to uppercase Default value is |
getSelectedItem |
ID of the element which is the current target of the association selectedItem, or |
getToplevelVariant |
Gets current value of property toplevelVariant. Defines whether the navigation bar shall have top-level appearance Default value is |
indexOfItem |
Checks for the provided |
insertItem |
Inserts a item into the aggregation items. |
isSelectedItemValid |
Returns whether there is a selectedItem set which is actually present in the items aggregation; or, if the aggregation is empty, in the associatedItems association. |
removeAllAssociatedItems |
Removes all the controls in the association named associatedItems. |
removeAllItems |
Removes all the controls from the aggregation items. Additionally, it unregisters them from the hosting UIArea. |
removeAssociatedItem |
Removes an associatedItem from the association named associatedItems. |
removeItem |
Removes a item from the aggregation items. |
setAssociatedItems |
Replaces the currently associated items with the ones in the given array |
setOverflowItemsToUpperCase |
Sets a new value for property overflowItemsToUpperCase. Sets the appearance of the menu items in the overflow menu to uppercase When called with a value of Default value is |
setSelectedItem |
Sets the associated selectedItem. |
setToplevelVariant |
Sets a new value for property toplevelVariant. Defines whether the navigation bar shall have top-level appearance When called with a value of Default value is |
Adds some associatedItem into the association associatedItems.
Param | Type | DefaultValue | Description |
---|---|---|---|
vAssociatedItem | sap.ui.core.ID sap.ui.ux3.NavigationItem |
The associatedItems to add; if empty, nothing is inserted |
Adds some item to the aggregation items.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.ui.ux3.NavigationItem |
The item to add; if empty, nothing is inserted |
Attaches event handler fnFunction
to the select event of this sap.ui.ux3.NavigationBar
.
When called, the context of the event handler (its this
) will be bound to oListener
if specified, otherwise it will be bound to this sap.ui.ux3.NavigationBar
itself.
Event is fired when an item is selected by the user
Param | Type | DefaultValue | Description |
---|---|---|---|
oData | object |
An application-specific payload object that will be passed to the event handler along with the event object when firing the event |
|
fnFunction | function(sap.ui.base.Event) : void |
The function to be called when the event occurs |
|
oListener | object |
Context object to call the event handler with. Defaults to this |
Detaches event handler fnFunction
from the select event of this sap.ui.ux3.NavigationBar
.
The passed function and listener object must match the ones used for event registration.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function(sap.ui.base.Event) : void |
The function to be called, when the event occurs |
|
oListener | object |
Context object on which the given function had to be called |
Fires event select to attached listeners.
Listeners may prevent the default action of this event by calling the preventDefault
method on the event object. The return value of this method indicates whether the default action should be executed.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
itemId | string |
The ID of the newly selected NavigationItem. |
|
item | sap.ui.ux3.NavigationItem |
The newly selected NavigationItem. |
Returns array of IDs of the elements which are the current targets of the association associatedItems.
Gets content of aggregation items.
If the navigation items need to have a different parent than the NavigationBar, alternatively the associatedItems association can be used. The NavigationBar follows the approach to use the items aggregation. If this aggregation is empty, associatedItems is used.
Gets current value of property overflowItemsToUpperCase.
Sets the appearance of the menu items in the overflow menu to uppercase
Default value is false
.
ID of the element which is the current target of the association selectedItem, or null
.
Gets current value of property toplevelVariant.
Defines whether the navigation bar shall have top-level appearance
Default value is false
.
Checks for the provided sap.ui.ux3.NavigationItem
in the aggregation items. and returns its index if found or -1 otherwise.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.ui.ux3.NavigationItem |
The item whose index is looked for |
Inserts a item into the aggregation items.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.ui.ux3.NavigationItem |
The item to insert; if empty, nothing is inserted |
|
iIndex | int |
The |
Returns whether there is a selectedItem set which is actually present in the items aggregation; or, if the aggregation is empty, in the associatedItems association.
Removes all the controls from the aggregation items.
Additionally, it unregisters them from the hosting UIArea.
Removes an associatedItem from the association named associatedItems.
Param | Type | DefaultValue | Description |
---|---|---|---|
vAssociatedItem | int sap.ui.core.ID sap.ui.ux3.NavigationItem |
The associatedItem to be removed or its index or ID |
Removes a item from the aggregation items.
Param | Type | DefaultValue | Description |
---|---|---|---|
vItem | int string sap.ui.ux3.NavigationItem |
The item to remove or its index or id |
Replaces the currently associated items with the ones in the given array
Param | Type | DefaultValue | Description |
---|---|---|---|
aItems | sap.ui.ux3.NavigationItem[] |
The items to associate |
Sets a new value for property overflowItemsToUpperCase.
Sets the appearance of the menu items in the overflow menu to uppercase
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is false
.
Param | Type | DefaultValue | Description |
---|---|---|---|
bOverflowItemsToUpperCase | boolean | false |
New value for property |
Sets the associated selectedItem.
Param | Type | DefaultValue | Description |
---|---|---|---|
oSelectedItem | sap.ui.core.ID sap.ui.ux3.NavigationItem |
ID of an element which becomes the new target of this selectedItem association; alternatively, an element instance may be given |
Sets a new value for property toplevelVariant.
Defines whether the navigation bar shall have top-level appearance
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is false
.
Param | Type | DefaultValue | Description |
---|---|---|---|
bToplevelVariant | boolean | false |
New value for property |