Namespace: Toolbar

sap. Toolbar

The Toolbar plugin allows an application to create a native toolbar using JavaScript. On Android, a double tap gesture is used to display/hide the toolbar. On iOS, A long press with 2 fingers will display the toolbar. On Windows Phone 8.1, the toolbar icon is always visible in the right bottom corner. Clicking on this icon will display the toolbar buttons. On Windows 8.1, A right mouse click or Press Windows+Z or Swipe from the top or bottom edge of the screen to display the toolbar. Click anywhere on the screen to hide it.

Members

(static, constant) SHOW_AS_ACTION_ALWAYS :number

Always show this item as a button in an Action Bar. It is recommended that at most 2 items have this set. Android Only.
Type:
  • number

(static, constant) SHOW_AS_ACTION_IF_ROOM :number

Show this item as a button in an Action Bar if the system decides there is room for it. Android Only.
Type:
  • number

(static, constant) SHOW_AS_ACTION_NEVER :number

Never show this item as a button in an Action Bar. Android Only.
Type:
  • number

(static, constant) SHOW_AS_ACTION_WITH_TEXT :number

When this item is in the action bar, always show it with a text label even if it also has an icon specified. Android Only.
Type:
  • number

Methods

(static) addEventListener(listener)

Adds an event listener to the Toolbar.
Parameters:
Name Type Description
listener sap.Toolbar.eventListener the listener to be added
Throws:
if the argument is not a function
Type
Error

(static) addItem(item, callback)

Adds a custom item to the toolbar. Top placement is not supported on Windows Phone 8.1. In this case the items will be added to the bottom toolbar.
Parameters:
Name Type Description
item Object Properties used for creating the toolbar item.
Properties
Name Type Attributes Description
id String <optional>
 The identifier of the item. Used only during usage collection. If it's absent then the label is going to be used.
label String The text for the toolbar item.
icon String The name of the icon to display for the toolbar item. The name is resolved to the platforms assets.
showAsAction number Sets how this item should be display with the Action Bar. One of `SHOW_AS_ACTION_ALWAYS`, `SHOW_AS_ACTION_IF_ROOM`, or `SHOW_AS_ACTION_NEVER`. Optionally you may OR the value with `SHOW_AS_ACTION_WITH_TEXT`. Defaults to `SHOW_AS_ACTION_NEVER`. Android Only.
callback function Callback function that is invoked when the item is clicked.
Example
sap.Toolbar.addItem({ "label" : "Refresh", "icon" : "smp_reload", "showAsAction" : sap.Toolbar.SHOW_AS_ACTION_ALWAYS }, function() {
    window.location.reload();
});

(static) clear(callback)

Clears all the custom items from the toolbar.
Parameters:
Name Type Description
callback function Callback function that is invoked when the clear is finished.
Example
sap.Toolbar.clear(function() {
    console.log("Cleared toolbar");
});

(static) disableUsage()

Disables collection of usage data. Does nothing if it's not enabled.

(static) enableUsage(type) → {boolean}

Enables collection of Toolbar usage data using the sap.Usage plugin. It will use the specified type to log certain events about how the toolbar is being interacted with by the user. Note that this method fails if the sap.Usage plugin is not present.

It's the caller's responsibility to initialize the Usage plugin prior to invoking this method.

Invoking this method when usage collection is already enabled has no effect.

Parameters:
Name Type Description
type string the type to use when invoking sap.Usage.log()
Returns:
true if usage collection was enabled, false if it failed because sap.Usage is not present or it was already enabled
Type
boolean

(static) removeEventListener(listener)

Removes an event listener from the Toolbar.
Parameters:
Name Type Description
listener sap.Toolbar.eventListener the listener to be removed
Throws:
if the argument is not a function
Type
Error

(static) setEnabled()

Enable/disable the toolbar. When disabled, the toolbar is not shown on double tap.
Example
sap.Toolbar.setEnabled(true);

(static) show()

Shows the toolbar
Example
sap.Toolbar.show();

Type Definitions

eventListener(eventId, itemIdopt)

Function invoked when an event occurs on the Toolbar
Parameters:
Name Type Attributes Description
eventId string the event id (can be 'show', 'hide' or 'itemClick')
itemId string <optional>
 the item id (can be 'home', 'refresh' and everything else the application added runtime) it is 'undefined' when the eventId is not 'itemClick'