class sap.m.Toolbar

Control sample: sap.m.Toolbar
Visiblity: public
UX Guidelines: Toolbar
Implements: sap.ui.core.Toolbarsap.m.IBar
Available since: N/A
Module: sap/m/Toolbar
Application Component: CA-UI5-CTR

Horizontal container most commonly used to display buttons, labels, selects and various other input controls.

Overview

By default, the Toolbar items are shrinkable if they have percent-based width (for example, sap.m.Input and sap.m.Slider) or implement the sap.ui.core.IShrinkable interface (for example, sap.m.Text and sap.m.Label). This behavior can be overridden by providing sap.m.ToolbarLayoutData for the Toolbar items.

Note: It is recommended that you use sap.m.OverflowToolbar over sap.m.Toolbar, unless you want to avoid the overflow behavior in favor of shrinking.

Usage

You can add a visual separator between the preceding and succeeding sap.m.Toolbar item with the use of the sap.m.ToolbarSeparator. The separator is theme dependent and can be a padding, a margin or a line.

To add horizontal space between the Toolbar items, use the sap.m.ToolbarSpacer. You can define the width of the horizontal space or make it flexible to cover the remaining space between the Toolbar items (for example, to to push an item to the edge of the Toolbar.

Note: The sap.m.ToolbarSpacer is a flex control that is intended to control its own behavior, thus sap.m.ToolbarLayoutData is not supported as value for the layoutData aggregation of sap.m.ToolbarSpacer and if set it's ignored.


Constructor

Constructor for a new Toolbar.

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.m.Toolbar(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


Properties

Name Type Default Value Description
active boolean false

Indicates that the whole toolbar is clickable. The Press event is fired only if Active is set to true. Note: This property should be used when there are no interactive controls inside the toolbar and the toolbar itself is meant to be interactive.

Visibility: public
ariaHasPopup string

Defines the aria-haspopup attribute of the Toolbar. if the active design is true.

Guidance for choosing appropriate value:

  • We recommend that you use the sap.ui.core.aria.HasPopup enumeration.
  • If you use controls based on sap.m.Popover or sap.m.Dialog, then you must use AriaHasPopup.Dialog (both sap.m.Popover and sap.m.Dialog have role "dialog" assigned internally).
  • If you use other controls, or directly sap.ui.core.Popup, you need to check the container role/type and map the value of ariaHasPopup accordingly.


Since: 1.79.0.

Visibility: public
design sap.m.ToolbarDesign Auto

Defines the toolbar design.

Note: Design settings are theme-dependent. They also determine the default height of the toolbar.

Since: 1.16.8.

Visibility: public
enabled boolean true

Sets the enabled property of all controls defined in the content aggregation. Note: This property does not apply to the toolbar itself, but rather to its items.

Visibility: public
height sap.ui.core.CSSSize empty string

Defines the height of the control. By default, the height property depends on the used theme and the design property.

Note: It is not recommended to use this property if the sapMTBHeader-CTX class is used

Visibility: public
style sap.m.ToolbarStyle Standard

Defines the visual style of the Toolbar.

Note: The visual styles are theme-dependent.

Since: 1.54.

Visibility: public
width sap.ui.core.CSSSize

Defines the width of the control. By default, Toolbar is a block element. If the width is not explicitly set, the control will assume its natural size.

Visibility: public

Aggregations

Default Aggregation: content

Name Cardinality Type Description
content (default) 0..n sap.ui.core.Control

The content of the toolbar.


Associations

Name Cardinality Type Description
ariaLabelledBy 0..n sap.ui.core.Control

Association to controls / ids which label this control (see WAI-ARIA attribute aria-labelledby).


Events Overview

Event Description
press

Fired when the user clicks on the toolbar, if the Active property is set to "true".

press

Fired when the user clicks on the toolbar, if the Active property is set to "true".

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
srcControl sap.ui.core.Control

The toolbar item that was pressed


Methods Overview

Method Description
_applyContextClassFor

Sets classes according to the context of the page. Possible contexts are header, footer and subheader.

_applyTag

Sets HTML tag according to the context of the page. Possible contexts are header, footer and subheader.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

addContent

Adds some content to the aggregation content.

applyTagAndContextClassFor

Sets classes and HTML tag according to the context of the page. Possible contexts are header, footer, subheader

attachPress

Attaches event handler fnFunction to the press event of this sap.m.Toolbar.

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.m.Toolbar itself.

Fired when the user clicks on the toolbar, if the Active property is set to "true".

destroyContent

Destroys all the content in the aggregation content.

detachPress

Detaches event handler fnFunction from the press event of this sap.m.Toolbar.

The passed function and listener object must match the ones used for event registration.

sap.m.Toolbar.extend

Creates a new subclass of class sap.m.Toolbar 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.core.Control.extend.

firePress

Fires event press to attached listeners.

getActive

Gets current value of property active.

Indicates that the whole toolbar is clickable. The Press event is fired only if Active is set to true. Note: This property should be used when there are no interactive controls inside the toolbar and the toolbar itself is meant to be interactive.

Default value is false.

getAriaHasPopup

Gets current value of property ariaHasPopup.

Defines the aria-haspopup attribute of the Toolbar. if the active design is true.

Guidance for choosing appropriate value:

  • We recommend that you use the sap.ui.core.aria.HasPopup enumeration.
  • If you use controls based on sap.m.Popover or sap.m.Dialog, then you must use AriaHasPopup.Dialog (both sap.m.Popover and sap.m.Dialog have role "dialog" assigned internally).
  • If you use other controls, or directly sap.ui.core.Popup, you need to check the container role/type and map the value of ariaHasPopup accordingly.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getContent

Gets content of aggregation content.

The content of the toolbar.

getDesign

Gets current value of property design.

Defines the toolbar design.

Note: Design settings are theme-dependent. They also determine the default height of the toolbar.

Default value is Auto.

getEnabled

Gets current value of property enabled.

Sets the enabled property of all controls defined in the content aggregation. Note: This property does not apply to the toolbar itself, but rather to its items.

Default value is true.

getHeight

Gets current value of property height.

Defines the height of the control. By default, the height property depends on the used theme and the design property.

Note: It is not recommended to use this property if the sapMTBHeader-CTX class is used

Default value is empty string.

getHTMLTag

Gets the HTML tag of the root domref

sap.m.Toolbar.getMetadata

Returns a metadata object for class sap.m.Toolbar.

getStyle

Gets current value of property style.

Defines the visual style of the Toolbar.

Note: The visual styles are theme-dependent.

Default value is Standard.

getTitleControl

Returns the first sap.m.Title control instance inside the toolbar for the accessibility

getTitleId

Returns the first sap.m.Title control id inside the toolbar for the accessibility

getWidth

Gets current value of property width.

Defines the width of the control. By default, Toolbar is a block element. If the width is not explicitly set, the control will assume its natural size.

indexOfContent

Checks for the provided sap.ui.core.Control in the aggregation content. and returns its index if found or -1 otherwise.

insertContent

Inserts a content into the aggregation content.

isContextSensitive

Returns if the bar is sensitive to the container context. Implementation of the IBar interface

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllContent

Removes all the controls from the aggregation content.

Additionally, it unregisters them from the hosting UIArea.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

removeContent

Removes a content from the aggregation content.

setActive

Sets a new value for property active.

Indicates that the whole toolbar is clickable. The Press event is fired only if Active is set to true. Note: This property should be used when there are no interactive controls inside the toolbar and the toolbar itself is meant to be interactive.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setAriaHasPopup

Sets a new value for property ariaHasPopup.

Defines the aria-haspopup attribute of the Toolbar. if the active design is true.

Guidance for choosing appropriate value:

  • We recommend that you use the sap.ui.core.aria.HasPopup enumeration.
  • If you use controls based on sap.m.Popover or sap.m.Dialog, then you must use AriaHasPopup.Dialog (both sap.m.Popover and sap.m.Dialog have role "dialog" assigned internally).
  • If you use other controls, or directly sap.ui.core.Popup, you need to check the container role/type and map the value of ariaHasPopup accordingly.

When called with a value of null or undefined, the default value of the property will be restored.

setDesign

Sets a new value for property design.

Defines the toolbar design.

Note: Design settings are theme-dependent. They also determine the default height of the toolbar.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Auto.

setEnabled

Sets a new value for property enabled.

Sets the enabled property of all controls defined in the content aggregation. Note: This property does not apply to the toolbar itself, but rather to its items.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setHeight

Sets a new value for property height.

Defines the height of the control. By default, the height property depends on the used theme and the design property.

Note: It is not recommended to use this property if the sapMTBHeader-CTX class is used

When called with a value of null or undefined, the default value of the property will be restored.

Default value is empty string.

setHTMLTag

Sets the HTML tag of the root domref

setStyle

Sets a new value for property style.

Defines the visual style of the Toolbar.

Note: The visual styles are theme-dependent.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Standard.

setWidth

Sets a new value for property width.

Defines the width of the control. By default, Toolbar is a block element. If the width is not explicitly set, the control will assume its natural size.

When called with a value of null or undefined, the default value of the property will be restored.

_applyContextClassFor

Sets classes according to the context of the page. Possible contexts are header, footer and subheader.

_applyTag

Sets HTML tag according to the context of the page. Possible contexts are header, footer and subheader.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to add; if empty, nothing is inserted

addContent

Adds some content to the aggregation content.

Param Type DefaultValue Description
oContent sap.ui.core.Control

The content to add; if empty, nothing is inserted

applyTagAndContextClassFor

Sets classes and HTML tag according to the context of the page. Possible contexts are header, footer, subheader

attachPress

Attaches event handler fnFunction to the press event of this sap.m.Toolbar.

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.m.Toolbar itself.

Fired when the user clicks on the toolbar, if the Active property is set to "true".

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 sap.m.Toolbar itself

destroyContent

Destroys all the content in the aggregation content.

detachPress

Detaches event handler fnFunction from the press event of this sap.m.Toolbar.

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

sap.m.Toolbar.extend

Creates a new subclass of class sap.m.Toolbar 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.core.Control.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

firePress

Fires event press to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

srcControl sap.ui.core.Control

The toolbar item that was pressed

getActive

Gets current value of property active.

Indicates that the whole toolbar is clickable. The Press event is fired only if Active is set to true. Note: This property should be used when there are no interactive controls inside the toolbar and the toolbar itself is meant to be interactive.

Default value is false.

getAriaHasPopup

Gets current value of property ariaHasPopup.

Defines the aria-haspopup attribute of the Toolbar. if the active design is true.

Guidance for choosing appropriate value:

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getContent

Gets content of aggregation content.

The content of the toolbar.

getDesign

Gets current value of property design.

Defines the toolbar design.

Note: Design settings are theme-dependent. They also determine the default height of the toolbar.

Default value is Auto.

getEnabled

Gets current value of property enabled.

Sets the enabled property of all controls defined in the content aggregation. Note: This property does not apply to the toolbar itself, but rather to its items.

Default value is true.

getHeight

Gets current value of property height.

Defines the height of the control. By default, the height property depends on the used theme and the design property.

Note: It is not recommended to use this property if the sapMTBHeader-CTX class is used

Default value is empty string.

getHTMLTag

Gets the HTML tag of the root domref

sap.m.Toolbar.getMetadata

Returns a metadata object for class sap.m.Toolbar.

getStyle

Gets current value of property style.

Defines the visual style of the Toolbar.

Note: The visual styles are theme-dependent.

Default value is Standard.

getTitleControl

Returns the first sap.m.Title control instance inside the toolbar for the accessibility

getTitleId

Returns the first sap.m.Title control id inside the toolbar for the accessibility

getWidth

Gets current value of property width.

Defines the width of the control. By default, Toolbar is a block element. If the width is not explicitly set, the control will assume its natural size.

indexOfContent

Checks for the provided sap.ui.core.Control in the aggregation content. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oContent sap.ui.core.Control

The content whose index is looked for

insertContent

Inserts a content into the aggregation content.

Param Type DefaultValue Description
oContent sap.ui.core.Control

The content to insert; if empty, nothing is inserted

iIndex int

The 0-based index the content should be inserted at; for a negative value of iIndex, the content is inserted at position 0; for a value greater than the current size of the aggregation, the content is inserted at the last position

isContextSensitive

Returns if the bar is sensitive to the container context. Implementation of the IBar interface

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllContent

Removes all the controls from the aggregation content.

Additionally, it unregisters them from the hosting UIArea.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy int sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to be removed or its index or ID

removeContent

Removes a content from the aggregation content.

Param Type DefaultValue Description
vContent int string sap.ui.core.Control

The content to remove or its index or id

setActive

Sets a new value for property active.

Indicates that the whole toolbar is clickable. The Press event is fired only if Active is set to true. Note: This property should be used when there are no interactive controls inside the toolbar and the toolbar itself is meant to be interactive.

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
bActive boolean false

New value for property active

setAriaHasPopup

Sets a new value for property ariaHasPopup.

Defines the aria-haspopup attribute of the Toolbar. if the active design is true.

Guidance for choosing appropriate value:

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sAriaHasPopup string

New value for property ariaHasPopup

setDesign

Sets a new value for property design.

Defines the toolbar design.

Note: Design settings are theme-dependent. They also determine the default height of the toolbar.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Auto.

Param Type DefaultValue Description
sDesign sap.m.ToolbarDesign Auto

New value for property design

setEnabled

Sets a new value for property enabled.

Sets the enabled property of all controls defined in the content aggregation. Note: This property does not apply to the toolbar itself, but rather to its items.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bEnabled boolean true

New value for property enabled

setHeight

Sets a new value for property height.

Defines the height of the control. By default, the height property depends on the used theme and the design property.

Note: It is not recommended to use this property if the sapMTBHeader-CTX class is used

When called with a value of null or undefined, the default value of the property will be restored.

Default value is empty string.

Param Type DefaultValue Description
sHeight sap.ui.core.CSSSize ''

New value for property height

setHTMLTag

Sets the HTML tag of the root domref

Param Type DefaultValue Description
sTag string

setStyle

Sets a new value for property style.

Defines the visual style of the Toolbar.

Note: The visual styles are theme-dependent.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Standard.

Param Type DefaultValue Description
sStyle sap.m.ToolbarStyle Standard

New value for property style

setWidth

Sets a new value for property width.

Defines the width of the control. By default, Toolbar is a block element. If the width is not explicitly set, the control will assume its natural size.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize

New value for property width