class sap.ui.commons.Button

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

Enables users to trigger actions such as save or print. For the button UI, you can define some text or an icon, or both.


Constructor

Constructor for a new Button.

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.Button(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
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

Associations

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

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

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

Event is fired when the user presses the control.

press

Event is fired when the user presses the control.

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

Methods Overview

Method Description
addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

attachPress

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

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.Button itself.

Event is fired when the user presses the control.

detachPress

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

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

sap.ui.commons.Button.extend

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

focus

Puts the focus to the button.

getAccessibilityInfo

References:

  • sap.ui.core.Control#getAccessibilityInfo

getAriaDescribedBy

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

getAriaLabelledBy

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

getEnabled

Gets current value of property enabled.

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

Default value is true.

getHeight

Gets current value of property height.

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

getHelpId

Gets current value of property helpId.

Unique identifier used for help service

Default value is empty string.

getIcon

Gets current value of property icon.

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

Default value is empty string.

getIconFirst

Gets current value of property iconFirst.

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

Default value is true.

getIconHovered

Gets current value of property iconHovered.

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.

Default value is empty string.

getIconSelected

Gets current value of property iconSelected.

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.

Default value is empty string.

getLite

Gets current value of property lite.

The button is rendered as lite button.

Default value is false.

sap.ui.commons.Button.getMetadata

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

getStyle

Gets current value of property style.

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

Default value is Default.

getStyled

Gets current value of property styled.

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.

Default value is true.

getText

Gets current value of property text.

Button text displayed at runtime.

Default value is empty string.

getWidth

Gets current value of property width.

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

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

setEnabled

Sets a new value for property enabled.

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

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.

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

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

setHelpId

Sets a new value for property helpId.

Unique identifier used for help service

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

Default value is empty string.

setIcon

Sets a new value for property icon.

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

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

Default value is empty string.

setIconFirst

Sets a new value for property iconFirst.

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

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

Default value is true.

setIconHovered

Sets a new value for property iconHovered.

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.

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

Default value is empty string.

setIconSelected

Sets a new value for property iconSelected.

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.

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

Default value is empty string.

setLite

Sets a new value for property lite.

The button is rendered as lite button.

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

Default value is false.

setStyle

Sets a new value for property style.

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

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

Default value is Default.

setStyled

Sets a new value for property styled.

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.

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

Default value is true.

setText

Sets a new value for property text.

Button text displayed at runtime.

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

Default value is empty string.

setWidth

Sets a new value for property width.

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

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

addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

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

The ariaDescribedBy to add; if empty, nothing is inserted

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

attachPress

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

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.Button itself.

Event is fired when the user presses the control.

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.Button itself

detachPress

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

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.ui.commons.Button.extend

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

focus

Puts the focus to the button.

getAccessibilityInfo

References:

getAriaDescribedBy

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

getAriaLabelledBy

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

getEnabled

Gets current value of property enabled.

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

Default value is true.

getHeight

Gets current value of property height.

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

getHelpId

Gets current value of property helpId.

Unique identifier used for help service

Default value is empty string.

getIcon

Gets current value of property icon.

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

Default value is empty string.

getIconFirst

Gets current value of property iconFirst.

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

Default value is true.

getIconHovered

Gets current value of property iconHovered.

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.

Default value is empty string.

getIconSelected

Gets current value of property iconSelected.

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.

Default value is empty string.

getLite

Gets current value of property lite.

The button is rendered as lite button.

Default value is false.

sap.ui.commons.Button.getMetadata

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

getStyle

Gets current value of property style.

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

Default value is Default.

getStyled

Gets current value of property styled.

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.

Default value is true.

getText

Gets current value of property text.

Button text displayed at runtime.

Default value is empty string.

getWidth

Gets current value of property width.

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

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

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

The ariaDescribedBy to be removed or its index or ID

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

setEnabled

Sets a new value for property enabled.

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

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.

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

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

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

New value for property height

setHelpId

Sets a new value for property helpId.

Unique identifier used for help service

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
sHelpId string ''

New value for property helpId

setIcon

Sets a new value for property icon.

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

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
sIcon sap.ui.core.URI ''

New value for property icon

setIconFirst

Sets a new value for property iconFirst.

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

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
bIconFirst boolean true

New value for property iconFirst

setIconHovered

Sets a new value for property iconHovered.

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.

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
sIconHovered sap.ui.core.URI ''

New value for property iconHovered

setIconSelected

Sets a new value for property iconSelected.

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.

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
sIconSelected sap.ui.core.URI ''

New value for property iconSelected

setLite

Sets a new value for property lite.

The button is rendered as lite button.

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

New value for property lite

setStyle

Sets a new value for property style.

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

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

Default value is Default.

Param Type DefaultValue Description
sStyle sap.ui.commons.ButtonStyle Default

New value for property style

setStyled

Sets a new value for property styled.

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.

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
bStyled boolean true

New value for property styled

setText

Sets a new value for property text.

Button text displayed at runtime.

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
sText string ''

New value for property text

setWidth

Sets a new value for property width.

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

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