class sap.ui.commons.MenuButton

Control sample: sap.ui.commons.MenuButton
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/commons/MenuButton
Application Component: CA-UI5-CTR

Common button control that opens a menu when clicked by the user. The control provides an API for configuring the docking position of the menu.


Constructor

Constructor for a new MenuButton.

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.commons.MenuButton(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
dockButton string

The position / edge (see sap.ui.core.Popup.Dock) of the button where the menu is docked. Default is 'begin bottom'.

Visibility: public
dockMenu string

The position / edge (see sap.ui.core.Popup.Dock) of the menu which is docked to the button. Default is 'begin top'.

Visibility: public

Borrowed Properties

Name Type Default Value Description
enabled boolean true

Boolean property to enable the control (default is true). Buttons that are disabled have other colors than enabled ones, depending on custom settings.

Visibility: public
height sap.ui.core.CSSSize

Specifies the button height. If this property is set, the height which is specified by the underlying theme is not used any longer.

Visibility: public
helpId string empty string

Unique identifier used for help service

Visibility: public
icon sap.ui.core.URI empty string

Icon to be displayed as graphical element within the button. This can be a URI to an image or an icon font URI.

Visibility: public
iconFirst boolean true

If set to true (default), the display sequence is 1. icon 2. control text .

Visibility: public
iconHovered sap.ui.core.URI empty string

Icon to be displayed as graphical element within the button when it is hovered (only if also a base icon was specified). If not specified the base icon is used. If an icon font icon is used, this property is ignored.

Visibility: public
iconSelected sap.ui.core.URI empty string

Icon to be displayed as graphical element within the button when it is selected (only if also a base icon was specified). If not specified the base or hovered icon is used. If an icon font icon is used, this property is ignored.

Visibility: public
lite boolean false

The button is rendered as lite button.

Visibility: public
style sap.ui.commons.ButtonStyle Default

Style of the button. (e.g. emphasized)

Visibility: public
styled boolean true

Indicates if the button is styled. If not it is rendered as native HTML-button. In this case a custom styling can be added usig addStyleClass.

Visibility: public
text string empty string

Button text displayed at runtime.

Visibility: public
width sap.ui.core.CSSSize

Control width as common CSS-size (px or % as unit, for example)

Visibility: public

Aggregations

Default Aggregation: menu

Name Cardinality Type Description
menu (default) 0..1 sap.ui.unified.Menu

Menu that shall be opened when the button is clicked


Events Overview

Event Description
itemSelected

Event that is fired when a menu item is selected by the user

press

Fired when an item from the menu was selected.

itemSelected

Event that is fired when a menu item is selected by the user

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
itemId string

The ID of the selected item

item sap.ui.unified.MenuItemBase

The selected item

press

Fired when an item from the menu was selected.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
itemId string

The id of the selected item

item sap.ui.commons.MenuItemBase

The selected item


Methods Overview

Method Description
attachItemSelected

Attaches event handler fnFunction to the itemSelected event of this sap.ui.commons.MenuButton.

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.commons.MenuButton itself.

Event that is fired when a menu item is selected by the user

attachPress

Attaches event handler fnFunction to the press event of this sap.ui.commons.MenuButton.

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.commons.MenuButton itself.

Event is fired when an item from the menu was selected.

References:

  • sap.ui.commons.MenuButton#attachItemSelected

destroyMenu

Destroys the menu in the aggregation named menu.

detachItemSelected

Detaches event handler fnFunction from the itemSelected event of this sap.ui.commons.MenuButton.

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

detachPress

Detaches event handler fnFunction from the press event of this sap.ui.commons.MenuButton.

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

References:

  • sap.ui.commons.MenuButton#detachItemSelected

sap.ui.commons.MenuButton.extend

Creates a new subclass of class sap.ui.commons.MenuButton 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.commons.Button.extend.

fireItemSelected

Fires event itemSelected to attached listeners.

firePress

Fires event press to attached listeners.

References:

  • sap.ui.commons.MenuButton#fireItemSelected

getDockButton

Gets current value of property dockButton.

The position / edge (see sap.ui.core.Popup.Dock) of the button where the menu is docked. Default is 'begin bottom'.

getDockMenu

Gets current value of property dockMenu.

The position / edge (see sap.ui.core.Popup.Dock) of the menu which is docked to the button. Default is 'begin top'.

getMenu

Gets content of aggregation menu.

Menu that shall be opened when the button is clicked

sap.ui.commons.MenuButton.getMetadata

Returns a metadata object for class sap.ui.commons.MenuButton.

setDockButton

Sets a new value for property dockButton.

The position / edge (see sap.ui.core.Popup.Dock) of the button where the menu is docked. Default is 'begin bottom'.

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

setDockMenu

Sets a new value for property dockMenu.

The position / edge (see sap.ui.core.Popup.Dock) of the menu which is docked to the button. Default is 'begin top'.

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

setMenu

Setter for the aggregated menu.

attachItemSelected

Attaches event handler fnFunction to the itemSelected event of this sap.ui.commons.MenuButton.

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.commons.MenuButton itself.

Event that is fired when a menu 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 sap.ui.commons.MenuButton itself

attachPress

Attaches event handler fnFunction to the press event of this sap.ui.commons.MenuButton.

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.commons.MenuButton itself.

Event is fired when an item from the menu was selected.

References:

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

The function to be called, when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.commons.MenuButton itself

destroyMenu

Destroys the menu in the aggregation named menu.

detachItemSelected

Detaches event handler fnFunction from the itemSelected event of this sap.ui.commons.MenuButton.

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

detachPress

Detaches event handler fnFunction from the press event of this sap.ui.commons.MenuButton.

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

References:

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.ui.commons.MenuButton.extend

Creates a new subclass of class sap.ui.commons.MenuButton 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.commons.Button.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

fireItemSelected

Fires event itemSelected to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

itemId string

The ID of the selected item

item sap.ui.unified.MenuItemBase

The selected item

firePress

Fires event press to attached listeners.

References:

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

getDockButton

Gets current value of property dockButton.

The position / edge (see sap.ui.core.Popup.Dock) of the button where the menu is docked. Default is 'begin bottom'.

getDockMenu

Gets current value of property dockMenu.

The position / edge (see sap.ui.core.Popup.Dock) of the menu which is docked to the button. Default is 'begin top'.

getMenu

Gets content of aggregation menu.

Menu that shall be opened when the button is clicked

sap.ui.commons.MenuButton.getMetadata

Returns a metadata object for class sap.ui.commons.MenuButton.

setDockButton

Sets a new value for property dockButton.

The position / edge (see sap.ui.core.Popup.Dock) of the button where the menu is docked. Default is 'begin bottom'.

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

Param Type DefaultValue Description
sDockButton string

New value for property dockButton

setDockMenu

Sets a new value for property dockMenu.

The position / edge (see sap.ui.core.Popup.Dock) of the menu which is docked to the button. Default is 'begin top'.

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

Param Type DefaultValue Description
sDockMenu string

New value for property dockMenu

setMenu

Setter for the aggregated menu.

Param Type DefaultValue Description
oMenu sap.ui.unified.Menu

The menu to be set to the menu aggregation