Class sap.ui.commons.ButtonModule: sap/ui/commons/Button

extends Control
known direct subclasses: MenuButton, ToggleButton

Enables users to trigger actions such as save or print. For the button UI, you can define some text or an icon, or both.
Deprecated API:
Since version 1.38. Instead, use the sap.m.Button control.
Constructor Summary
new sap.ui.commons.Button(sId?, mSettings?)Constructor for a new Button.
Event Summary
press(oControlEvent)Event is fired when the user presses the control.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.ui.commons.Button.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.ui.commons.Button with name sClassName and enriches it with the information contained in oClassInfo.
sap.ui.commons.Button.getMetadata()Returns a metadata object for class sap.ui.commons.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.ui.commons.Button.
detachPress(fnFunction, oListener)Detaches event handler fnFunction from the press event of this sap.ui.commons.Button.
firePress(mParameters?)Fires event press to attached listeners.
focus()Puts the focus to the button.
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.
getHeight()Gets current value of property height.
getHelpId()Gets current value of property helpId.
getIcon()Gets current value of property icon.
getIconFirst()Gets current value of property iconFirst.
getIconHovered()Gets current value of property iconHovered.
getIconSelected()Gets current value of property iconSelected.
getLite()Gets current value of property lite.
getStyle()Gets current value of property style.
getStyled()Gets current value of property styled.
getText()Gets current value of property text.
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.
setEnabled(bEnabled)Sets a new value for property enabled.
setHeight(sHeight)Sets a new value for property height.
setHelpId(sHelpId)Sets a new value for property helpId.
setIcon(sIcon)Sets a new value for property icon.
setIconFirst(bIconFirst)Sets a new value for property iconFirst.
setIconHovered(sIconHovered)Sets a new value for property iconHovered.
setIconSelected(sIconSelected)Sets a new value for property iconSelected.
setLite(bLite)Sets a new value for property lite.
setStyle(sStyle)Sets a new value for property style.
setStyled(bStyled)Sets a new value for property styled.
setText(sText)Sets a new value for property text.
setWidth(sWidth)Sets a new value for property width.
Constructor Detail
new sap.ui.commons.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

    • text : string (default: )
    • enabled : boolean (default: true)
    • width : sap.ui.core.CSSSize
    • helpId : string (default: )
    • icon : sap.ui.core.URI (default: )
    • iconHovered : sap.ui.core.URI (default: )
    • iconSelected : sap.ui.core.URI (default: )
    • iconFirst : boolean (default: true)
    • height : sap.ui.core.CSSSize
    • styled : boolean (default: true)
    • lite : boolean (default: false)
    • style : sap.ui.commons.ButtonStyle (default: Default)

  • Associations

  • Events

    • 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)
Event is fired when the user presses the control.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
Method Detail
sap.ui.commons.Button.extend(sClassName, oClassInfo?, FNMetaImpl?): function

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.

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.ui.commons.Button.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.ui.commons.Button.
Returns:
sap.ui.base.MetadataMetadata object describing this class
addAriaDescribedBy(vAriaDescribedBy): sap.ui.commons.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.ui.commons.ButtonReference to this in order to allow method chaining
addAriaLabelledBy(vAriaLabelledBy): sap.ui.commons.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.ui.commons.ButtonReference to this in order to allow method chaining
attachPress(oData?, fnFunction, oListener?): sap.ui.commons.Button

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.

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.ui.commons.Button itself
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
detachPress(fnFunction, oListener): sap.ui.commons.Button

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.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
firePress(mParameters?): sap.ui.commons.Button
Fires event press to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
focus(): void
Puts the focus to the button.
getAccessibilityInfo(): Object
Returns:
ObjectCurrent accessibility state of the control.
See:
sap.ui.core.Control#getAccessibilityInfo
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.

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.

Returns:
booleanValue of property enabled
getHeight(): sap.ui.core.CSSSize

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.

Returns:
sap.ui.core.CSSSizeValue of property height
getHelpId(): string

Gets current value of property helpId.

Unique identifier used for help service

Default value is .

Returns:
stringValue of property helpId
getIcon(): sap.ui.core.URI

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 .

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

Gets current value of property iconFirst.

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

Default value is true.

Returns:
booleanValue of property iconFirst
getIconHovered(): sap.ui.core.URI

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 .

Returns:
sap.ui.core.URIValue of property iconHovered
getIconSelected(): sap.ui.core.URI

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 .

Returns:
sap.ui.core.URIValue of property iconSelected
getLite(): boolean

Gets current value of property lite.

The button is rendered as lite button.

Default value is false.

Returns:
booleanValue of property lite

Gets current value of property style.

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

Default value is Default.

Returns:
sap.ui.commons.ButtonStyleValue of property style
getStyled(): boolean

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.

Returns:
booleanValue of property styled
getText(): string

Gets current value of property text.

Button text displayed at runtime.

Default value is .

Returns:
stringValue of property text
getWidth(): sap.ui.core.CSSSize

Gets current value of property width.

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

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
setEnabled(bEnabled): sap.ui.commons.Button

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.

Parameters:
booleanbEnabledNew value for property enabled
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
setHeight(sHeight): sap.ui.commons.Button

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.

Parameters:
sap.ui.core.CSSSizesHeightNew value for property height
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
setHelpId(sHelpId): sap.ui.commons.Button

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 .

Parameters:
stringsHelpIdNew value for property helpId
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
setIcon(sIcon): sap.ui.commons.Button

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 .

Parameters:
sap.ui.core.URIsIconNew value for property icon
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
setIconFirst(bIconFirst): sap.ui.commons.Button

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.

Parameters:
booleanbIconFirstNew value for property iconFirst
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
setIconHovered(sIconHovered): sap.ui.commons.Button

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 .

Parameters:
sap.ui.core.URIsIconHoveredNew value for property iconHovered
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
setIconSelected(sIconSelected): sap.ui.commons.Button

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 .

Parameters:
sap.ui.core.URIsIconSelectedNew value for property iconSelected
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
setLite(bLite): sap.ui.commons.Button

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.

Parameters:
booleanbLiteNew value for property lite
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
setStyle(sStyle): sap.ui.commons.Button

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.

Parameters:
sap.ui.commons.ButtonStylesStyleNew value for property style
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
setStyled(bStyled): sap.ui.commons.Button

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.

Parameters:
booleanbStyledNew value for property styled
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
setText(sText): sap.ui.commons.Button

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 .

Parameters:
stringsTextNew value for property text
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining
setWidth(sWidth): sap.ui.commons.Button

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.

Parameters:
sap.ui.core.CSSSizesWidthNew value for property width
Returns:
sap.ui.commons.ButtonReference to this in order to allow method chaining