class sap.m.ToggleButton

Control sample: sap.m.ToggleButton
Visiblity: public
UX Guidelines: Toggle Button
Implements:
Available since: N/A
Extends: sap.m.Button
Module: sap/m/ToggleButton
Application Component: CA-UI5-CTR

An enhanced sap.m.Button that can be toggled between pressed and normal state.

Clicking or tapping a ToggleButton changes its state to pressed. The button returns to its initial state when the user clicks or taps it again.


Constructor

Constructor for a new ToggleButton.

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.m.ToggleButton(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
pressed boolean false

The property is “true” when the control is toggled. The default state of this property is "false".

Visibility: public

Borrowed Properties

Name Type Default Value Description
activeIcon sap.ui.core.URI

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.

Visibility: public
ariaHasPopup sap.ui.core.aria.HasPopup None

Specifies the value of the aria-haspopup attribute

If the value is None, the attribute will not be rendered. Otherwise it will be rendered with the selected value.

NOTE: Use this property only when a button is related to a popover/popup. The value needs to be equal to the main/root role of the popup - e.g. dialog, menu or list (examples: if you have dialog -> dialog, if you have menu -> menu; if you have list -> list; if you have dialog containing a list -> dialog). Do not use it, if you open a standard sap.m.Dialog, MessageBox or other type of dialogs displayed as on overlay over the application.

Since: 1.84.0.

Visibility: public
enabled boolean true

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

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

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

Visibility: public
iconDensityAware boolean true

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.

Visibility: public
iconFirst boolean true

Determines whether the icon is displayed before the text.

Visibility: public
text string empty string

Determines the text of the Button.

Visibility: public
textDirection sap.ui.core.TextDirection Inherit

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

Since: 1.28.0.

Visibility: public
type sap.m.ButtonType Default

Defines the Button type.

Visibility: public
width sap.ui.core.CSSSize

Defines the Button width.

Visibility: public

Events Overview

Event Description
press

Fired when the user clicks or taps on the control.

press

Fired when the user clicks or taps on the control.

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

The current pressed state of the control.


Methods Overview

Method Description
attachPress

Attaches event handler fnFunction to the press event of this sap.m.ToggleButton.

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

Fired when the user clicks or taps on the control.

detachPress

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

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

sap.m.ToggleButton.extend

Creates a new subclass of class sap.m.ToggleButton with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.m.Button.extend.

firePress

Fires event press to attached listeners.

getAccessibilityInfo

References:

  • sap.ui.core.Control#getAccessibilityInfo

sap.m.ToggleButton.getMetadata

Returns a metadata object for class sap.m.ToggleButton.

getPressed

Gets current value of property pressed.

The property is “true” when the control is toggled. The default state of this property is "false".

Default value is false.

setPressed

Sets a new value for property pressed.

The property is “true” when the control is toggled. The default state of this property is "false".

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

Default value is false.

attachPress

Attaches event handler fnFunction to the press event of this sap.m.ToggleButton.

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

Fired when the user clicks or taps on 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.m.ToggleButton itself

detachPress

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

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.m.ToggleButton.extend

Creates a new subclass of class sap.m.ToggleButton with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.m.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

firePress

Fires event press to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

pressed boolean

The current pressed state of the control.

getAccessibilityInfo

References:

sap.m.ToggleButton.getMetadata

Returns a metadata object for class sap.m.ToggleButton.

getPressed

Gets current value of property pressed.

The property is “true” when the control is toggled. The default state of this property is "false".

Default value is false.

setPressed

Sets a new value for property pressed.

The property is “true” when the control is toggled. The default state of this property is "false".

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

New value for property pressed