Button

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

validateFieldGroup

Events borrowed from class sap.ui.base.ManagedObject

formatError, modelContextChange, parseError, validationError, validationSuccess

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(mArguments?)Fires event press to attached listeners.

focus()Puts the focus to the button.

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.

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.

Methods borrowed from class sap.ui.core.Control

Methods borrowed from class sap.ui.core.Element

Methods borrowed from class sap.ui.base.ManagedObject

addAggregation, addAssociation, applySettings, attachFormatError, attachModelContextChange, attachParseError, attachValidationError, attachValidationSuccess, bindAggregation, bindContext, bindObject, bindProperty, destroyAggregation, detachFormatError, detachModelContextChange, detachParseError, detachValidationError, detachValidationSuccess, findAggregatedObjects, fireFormatError, fireModelContextChange, fireParseError, fireValidationError, fireValidationSuccess, getAggregation, getAssociation, getBinding, getBindingContext, getBindingInfo, getBindingPath, getEventingParent, getId, getModel, getObjectBinding, getOriginInfo, getParent, getProperty, hasModel, indexOfAggregation, insertAggregation, isBound, isInvalidateSuppressed, isTreeBinding, propagateMessages, removeAggregation, removeAllAggregation, removeAllAssociation, removeAssociation, setAggregation, setAssociation, setBindingContext, setModel, setProperty, unbindAggregation, unbindContext, unbindObject, unbindProperty, validateAggregation, validateProperty

Methods borrowed from class sap.ui.base.EventProvider

attachEvent, attachEventOnce, detachEvent, hasListeners

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)
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:

{string}	sId?	id for the new control, generated automatically if no id is given
{object}	mSettings?	initial settings for the new control

Deprecated:
Since version 1.38. Instead, use the sap.m.Button control.

Event Detail

press(oControlEvent)

Event is fired when the user presses the control.

Parameters:

{sap.ui.base.Event}	oControlEvent
{sap.ui.base.EventProvider}	oControlEvent.getSource
{object}	oControlEvent.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:

{string}	sClassName	Name of the class being created
{object}	oClassInfo?	Object literal with information about the class
{function}	FNMetaImpl?	Constructor function for the metadata object; if not given, it defaults to `sap.ui.core.ElementMetadata`

Returns:

{function}

Created 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.Metadata}

Metadata object describing this class

addAriaDescribedBy(vAriaDescribedBy): sap.ui.commons.Button

Adds some ariaDescribedBy into the association ariaDescribedBy.

Parameters:

{string|sap.ui.core.Control}

vAriaDescribedBy

the ariaDescribedBy to add; if empty, nothing is inserted

Returns:

{sap.ui.commons.Button} Reference to this in order to allow method chaining

addAriaLabelledBy(vAriaLabelledBy): sap.ui.commons.Button

Adds some ariaLabelledBy into the association ariaLabelledBy.

Parameters:

{string|sap.ui.core.Control}

vAriaLabelledBy

the ariaLabelledBy to add; if empty, nothing is inserted

Returns:

{sap.ui.commons.Button} Reference 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:

{object}	oData?	An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}	fnFunction	The function to be called when the event occurs
{object}	oListener?	Context object to call the event handler with. Defaults to this `sap.ui.commons.Button` itself

Returns:

{sap.ui.commons.Button} Reference 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:

{function}	fnFunction	The function to be called, when the event occurs
{object}	oListener	Context object on which the given function had to be called

Returns:

{sap.ui.commons.Button} Reference to this in order to allow method chaining

firePress(mArguments?): sap.ui.commons.Button

Fires event press to attached listeners.

Parameters:

{Map}

mArguments?

The arguments to pass along with the event

Returns:

{sap.ui.commons.Button} Reference to this in order to allow method chaining

focus(): void

Puts the focus to the button.

getAccessibilityInfo()

See:

{sap.ui.core.Control#getAccessibilityInfo}

getAriaDescribedBy(): sap.ui.core.Control[]

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

Returns:

{sap.ui.core.Control[]}

getAriaLabelledBy(): sap.ui.core.Control[]

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

Returns:

{sap.ui.core.Control[]}

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:

{boolean} Value 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.CSSSize} Value of property height

getHelpId(): string

Gets current value of property helpId.

Unique identifier used for help service

Default value is .

Returns:

{string} Value 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 an URI to an image or an icon font URI.

Default value is .

Returns:

{sap.ui.core.URI} Value 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:

{boolean} Value 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 a icon font icon is used, this property is ignored.

Default value is .

Returns:

{sap.ui.core.URI} Value 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 a icon font icon is used, this property is ignored.

Default value is .

Returns:

{sap.ui.core.URI} Value of property iconSelected

getLite(): boolean

Gets current value of property lite.

The button is rendered as lite button.

Default value is false.

Returns:

{boolean} Value of property lite

getStyle(): sap.ui.commons.ButtonStyle

Gets current value of property style.

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

Default value is Default.

Returns:

{sap.ui.commons.ButtonStyle} Value 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:

{boolean} Value of property styled

getText(): string

Gets current value of property text.

Button text displayed at runtime.

Default value is .

Returns:

{string} Value 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.CSSSize} Value of property width

removeAllAriaDescribedBy(): sap.ui.core.Control[]

Removes all the controls in the association named ariaDescribedBy.

Returns:

{sap.ui.core.Control[]}

An array of the removed elements (might be empty)

removeAllAriaLabelledBy(): sap.ui.core.Control[]

Removes all the controls in the association named ariaLabelledBy.

Returns:

{sap.ui.core.Control[]}

An array of the removed elements (might be empty)

removeAriaDescribedBy(vAriaDescribedBy): sap.ui.core.Control

Removes an ariaDescribedBy from the association named ariaDescribedBy.

Parameters:

{int|string|sap.ui.core.Control}

vAriaDescribedBy

The ariaDescribedByto be removed or its index or ID

Returns:

{sap.ui.core.Control} the removed ariaDescribedBy or null

removeAriaLabelledBy(vAriaLabelledBy): sap.ui.core.Control

Removes an ariaLabelledBy from the association named ariaLabelledBy.

Parameters:

{int|string|sap.ui.core.Control}

vAriaLabelledBy

The ariaLabelledByto be removed or its index or ID

Returns:

{sap.ui.core.Control} the 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:

{boolean} bEnabled New value for property enabled

Returns:

{sap.ui.commons.Button} Reference 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.CSSSize} sHeight New value for property height

Returns:

{sap.ui.commons.Button} Reference 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:

{string} sHelpId New value for property helpId

Returns:

{sap.ui.commons.Button} Reference 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 an 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.URI} sIcon New value for property icon

Returns:

{sap.ui.commons.Button} Reference 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:

{boolean} bIconFirst New value for property iconFirst

Returns:

{sap.ui.commons.Button} Reference to this in order to allow method chaining

setIconHovered(sIconHovered): sap.ui.commons.Button

Sets a new value for property iconHovered.

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.URI} sIconHovered New value for property iconHovered

Returns:

{sap.ui.commons.Button} Reference to this in order to allow method chaining

setIconSelected(sIconSelected): sap.ui.commons.Button

Sets a new value for property iconSelected.

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.URI} sIconSelected New value for property iconSelected

Returns:

{sap.ui.commons.Button} Reference 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:

{boolean} bLite New value for property lite

Returns:

{sap.ui.commons.Button} Reference 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.ButtonStyle} sStyle New value for property style

Returns:

{sap.ui.commons.Button} Reference 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:

{boolean} bStyled New value for property styled

Returns:

{sap.ui.commons.Button} Reference 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:

{string} sText New value for property text

Returns:

{sap.ui.commons.Button} Reference 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.CSSSize} sWidth New value for property width

Returns:

{sap.ui.commons.Button} Reference to this in order to allow method chaining