Class sap.m.ButtonModule: sap/m/Button

extends Control
implements IFormContent

Enables users to trigger actions.

Overview

The user triggers an action by clicking or tapping the Button or by pressing certain keyboard keys, such as Enter.

Usage

For the Button UI, you can define text, icon, or both. You can also specify whether the text or the icon is displayed first.

You can choose from a set of predefined ButtonTypes that offer different styling to correspond to the triggered action.

You can set the Button as enabled or disabled. An enabled Button can be pressed by clicking or tapping it and it changes its style to provide visual feedback to the user that it is pressed or hovered over with the mouse cursor. A disabled Button appears inactive and cannot be pressed.

Constructor Summary
new sap.m.Button(sId?, mSettings?)Constructor for a new Button.
Event Summary
press(oControlEvent)Fired when the user clicks or taps on the control.
tap(oControlEvent)Fired when the user taps the control.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.m.Button.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.Button with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.Button.getMetadata()Returns a metadata object for class sap.m.Button.
addAriaDescribedBy(vAriaDescribedBy)Adds some ariaDescribedBy into the association ariaDescribedBy.
addAriaLabelledBy(vAriaLabelledBy)Adds some ariaLabelledBy into the association ariaLabelledBy.
attachPress(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the press event of this sap.m.Button.
detachPress(fnFunction, oListener)Detaches event handler fnFunction from the press event of this sap.m.Button.
firePress(mParameters?)Fires event press to attached listeners.
getActiveIcon()Gets current value of property activeIcon.
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.
getIcon()Gets current value of property icon.
getIconDensityAware()Gets current value of property iconDensityAware.
getIconFirst()Gets current value of property iconFirst.
getPopupAnchorDomRef()Defines to which DOM reference the Popup should be docked
getText()Gets current value of property text.
getTextDirection()Gets current value of property textDirection.
getType()Gets current value of property type.
getWidth()Gets current value of property width.
removeAllAriaDescribedBy()Removes all the controls in the association named ariaDescribedBy.
removeAllAriaLabelledBy()Removes all the controls in the association named ariaLabelledBy.
removeAriaDescribedBy(vAriaDescribedBy)Removes an ariaDescribedBy from the association named ariaDescribedBy.
removeAriaLabelledBy(vAriaLabelledBy)Removes an ariaLabelledBy from the association named ariaLabelledBy.
setActiveIcon(sActiveIcon)Sets a new value for property activeIcon.
setEnabled(bEnabled)Sets a new value for property enabled.
setIcon(sIcon)Property setter for the icon
setIconDensityAware(bIconDensityAware)Sets a new value for property iconDensityAware.
setIconFirst(bIconFirst)Sets a new value for property iconFirst.
setText(sText)Property setter for the text
setTextDirection(sTextDirection)Sets a new value for property textDirection.
setType(sType)Sets a new value for property type.
setWidth(sWidth)Sets a new value for property width.
attachTap(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the tap event of this sap.m.Button.
detachTap(fnFunction, oListener)Detaches event handler fnFunction from the tap event of this sap.m.Button.
fireTap(mParameters?)Fires event tap to attached listeners.
Constructor Detail
new sap.m.Button(sId?, mSettings?)

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 for a general description of the syntax of the settings object.

The supported settings are:

  • Properties

  • Associations

  • Events

    • tap : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • press : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]

In addition, all settings applicable to the base type sap.ui.core.Control can be used as well.

Parameters:
stringsId?ID for the new control, generated automatically if no ID is given
objectmSettings?Initial settings for the new control
Event Detail
press(oControlEvent)
Fired when the user clicks or taps on the control.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
tap(oControlEvent)
Fired when the user taps the control.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
Deprecated API:
As of version 1.20, use the press event instead
Method Detail
sap.m.Button.extend(sClassName, oClassInfo?, FNMetaImpl?): function

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

Parameters:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.m.Button.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.Button.
Returns:
sap.ui.base.MetadataMetadata object describing this class
addAriaDescribedBy(vAriaDescribedBy): sap.m.Button
Adds some ariaDescribedBy into the association ariaDescribedBy.
Parameters:
sap.ui.core.ID|sap.ui.core.ControlvAriaDescribedBythe ariaDescribedBy to add; if empty, nothing is inserted
Returns:
sap.m.ButtonReference to this in order to allow method chaining
addAriaLabelledBy(vAriaLabelledBy): sap.m.Button
Adds some ariaLabelledBy into the association ariaLabelledBy.
Parameters:
sap.ui.core.ID|sap.ui.core.ControlvAriaLabelledBythe ariaLabelledBy to add; if empty, nothing is inserted
Returns:
sap.m.ButtonReference to this in order to allow method chaining
attachPress(oData?, fnFunction, oListener?): sap.m.Button

Attaches event handler fnFunction to the press event of this sap.m.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.m.Button itself.

Fired when the user clicks or taps on the control.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Button itself
Returns:
sap.m.ButtonReference to this in order to allow method chaining
detachPress(fnFunction, oListener): sap.m.Button

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

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

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.ButtonReference to this in order to allow method chaining
firePress(mParameters?): sap.m.Button
Fires event press to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.ButtonReference to this in order to allow method chaining
getAccessibilityInfo(): Object
Returns:
ObjectCurrent accessibility state of the control
See:
sap.ui.core.Control#getAccessibilityInfo
getActiveIcon(): sap.ui.core.URI

Gets current value of property activeIcon.

The source property of an alternative icon for the active (depressed) state of the button. Both active and default icon properties should be defined and have the same type: image or icon font. If the icon property is not set or has a different type, the active icon is not displayed.

Returns:
sap.ui.core.URIValue of property activeIcon
getAriaDescribedBy(): sap.ui.core.ID[]
Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.
Returns:
sap.ui.core.ID[]
getAriaLabelledBy(): sap.ui.core.ID[]
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
Returns:
sap.ui.core.ID[]
getEnabled(): boolean

Gets current value of property enabled.

Determines whether the Button is enabled (default is set to true). A disabled Button has different colors depending on the ButtonType.

Default value is true.

Returns:
booleanValue of property enabled
getIcon(): sap.ui.core.URI

Gets current value of property icon.

Defines the icon to be displayed as graphical element within the Button. It can be an image or an icon from the icon font.

Returns:
sap.ui.core.URIValue of property icon
getIconDensityAware(): boolean

Gets current value of property iconDensityAware.

By default, this is set to true but then one or more requests are sent trying to get the density perfect version of image if this version of image doesn't exist on the server.

If only one version of image is provided, set this value to false to avoid the attempt of fetching density perfect image.

Default value is true.

Returns:
booleanValue of property iconDensityAware
getIconFirst(): boolean

Gets current value of property iconFirst.

Determines whether the icon is displayed before the text.

Default value is true.

Returns:
booleanValue of property iconFirst
getPopupAnchorDomRef(): DomNode
Defines to which DOM reference the Popup should be docked
Returns:
DomNodethe DOM reference that Popup should dock to
getText(): string

Gets current value of property text.

Determines the text of the Button.

Returns:
stringValue of property text
getTextDirection(): sap.ui.core.TextDirection

Gets current value of property textDirection.

This property specifies the element's text directionality with enumerated options. By default, the control inherits text direction from the DOM.

Default value is Inherit.

Returns:
sap.ui.core.TextDirectionValue of property textDirection
Since:
1.28.0
getType(): sap.m.ButtonType

Gets current value of property type.

Defines the Button type.

Default value is Default.

Returns:
sap.m.ButtonTypeValue of property type
getWidth(): sap.ui.core.CSSSize

Gets current value of property width.

Defines the Button width.

Returns:
sap.ui.core.CSSSizeValue of property width
removeAllAriaDescribedBy(): sap.ui.core.ID[]
Removes all the controls in the association named ariaDescribedBy.
Returns:
sap.ui.core.ID[]An array of the removed elements (might be empty)
removeAllAriaLabelledBy(): sap.ui.core.ID[]
Removes all the controls in the association named ariaLabelledBy.
Returns:
sap.ui.core.ID[]An array of the removed elements (might be empty)
removeAriaDescribedBy(vAriaDescribedBy): sap.ui.core.ID
Removes an ariaDescribedBy from the association named ariaDescribedBy.
Parameters:
int|sap.ui.core.ID|sap.ui.core.ControlvAriaDescribedByThe ariaDescribedBy to be removed or its index or ID
Returns:
sap.ui.core.IDThe removed ariaDescribedBy or null
removeAriaLabelledBy(vAriaLabelledBy): sap.ui.core.ID
Removes an ariaLabelledBy from the association named ariaLabelledBy.
Parameters:
int|sap.ui.core.ID|sap.ui.core.ControlvAriaLabelledByThe ariaLabelledBy to be removed or its index or ID
Returns:
sap.ui.core.IDThe removed ariaLabelledBy or null
setActiveIcon(sActiveIcon): sap.m.Button

Sets a new value for property activeIcon.

The source property of an alternative icon for the active (depressed) state of the button. Both active and default icon properties should be defined and have the same type: image or icon font. If the icon property is not set or has a different type, the active icon is not displayed.

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

Parameters:
sap.ui.core.URIsActiveIconNew value for property activeIcon
Returns:
sap.m.ButtonReference to this in order to allow method chaining
setEnabled(bEnabled): sap.m.Button

Sets a new value for property enabled.

Determines whether the Button is enabled (default is set to true). A disabled Button has different colors depending on the ButtonType.

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

Default value is true.

Parameters:
booleanbEnabledNew value for property enabled
Returns:
sap.m.ButtonReference to this in order to allow method chaining
setIcon(sIcon): sap.m.Button
Property setter for the icon
Parameters:
sap.ui.core.URIsIconnew value of the Icon property
Returns:
sap.m.Buttonthis to allow method chaining
setIconDensityAware(bIconDensityAware): sap.m.Button

Sets a new value for property iconDensityAware.

By default, this is set to true but then one or more requests are sent trying to get the density perfect version of image if this version of image doesn't exist on the server.

If only one version of image is provided, set this value to false to avoid the attempt of fetching density perfect image.

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

Default value is true.

Parameters:
booleanbIconDensityAwareNew value for property iconDensityAware
Returns:
sap.m.ButtonReference to this in order to allow method chaining
setIconFirst(bIconFirst): sap.m.Button

Sets a new value for property iconFirst.

Determines whether the icon is displayed before the text.

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

Default value is true.

Parameters:
booleanbIconFirstNew value for property iconFirst
Returns:
sap.m.ButtonReference to this in order to allow method chaining
setText(sText): sap.m.Button
Property setter for the text
Parameters:
stringsTextnew value of the Text attribute
Returns:
sap.m.Buttonthis to allow method chaining
setTextDirection(sTextDirection): sap.m.Button

Sets a new value for property textDirection.

This property specifies the element's text directionality with enumerated options. By default, the control inherits text direction from the DOM.

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

Default value is Inherit.

Parameters:
sap.ui.core.TextDirectionsTextDirectionNew value for property textDirection
Returns:
sap.m.ButtonReference to this in order to allow method chaining
Since:
1.28.0
setType(sType): sap.m.Button

Sets a new value for property type.

Defines the Button type.

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

Default value is Default.

Parameters:
sap.m.ButtonTypesTypeNew value for property type
Returns:
sap.m.ButtonReference to this in order to allow method chaining
setWidth(sWidth): sap.m.Button

Sets a new value for property width.

Defines the Button width.

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

Parameters:
sap.ui.core.CSSSizesWidthNew value for property width
Returns:
sap.m.ButtonReference to this in order to allow method chaining
attachTap(oData?, fnFunction, oListener?): sap.m.Button

Attaches event handler fnFunction to the tap event of this sap.m.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.m.Button itself.

Fired when the user taps the control.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Button itself
Returns:
sap.m.ButtonReference to this in order to allow method chaining
Deprecated API:
As of version 1.20, use the press event instead
detachTap(fnFunction, oListener): sap.m.Button

Detaches event handler fnFunction from the tap event of this sap.m.Button.

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

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.ButtonReference to this in order to allow method chaining
Deprecated API:
As of version 1.20, use the press event instead
fireTap(mParameters?): sap.m.Button
Fires event tap to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.ButtonReference to this in order to allow method chaining
Deprecated API:
As of version 1.20, use the press event instead