class sap.m.SegmentedButton

Control sample: sap.m.SegmentedButton
Visiblity: public
UX Guidelines: Segmented Button
Implements: sap.ui.core.IFormContentsap.m.IOverflowToolbarContent
Available since: N/A
Module: sap/m/SegmentedButton
Application Component: CA-UI5-CTR

A horizontal control made of multiple buttons, which can display a title or an image.

Overview

The SegmentedButton shows a group of buttons. When the user clicks or taps one of the buttons, it stays in a pressed state. It automatically resizes the buttons to fit proportionally within the control. When no width is set, the control uses the available width.

This control can be a drag source.

Constructor

Constructor for a new SegmentedButton.

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

Disables all the buttons in the SegmentedButton control. When disabled all the buttons look grey and you cannot focus or click on them.

Visibility: public
selectedKey string empty string

Key of the selected item. If no item to this key is found in the items aggregation, no changes will apply. Only the items aggregation is affected. If duplicate keys exist, the first item matching the key is used.

Since: 1.28.0.

Visibility: public
width sap.ui.core.CSSSize

Defines the width of the SegmentedButton control. If not set, it uses the minimum required width to make all buttons inside of the same size (based on the biggest button).

Visibility: public

Aggregations

Default Aggregation: buttons

Name Cardinality Type Description
_select 0..1 sap.m.Select

Hidden aggregation that holds an instance of sap.m.Select to be used in some contexts as a representation of the segmented button (for example, in a popover with little space).

buttons (default) 0..n sap.m.Button

The buttons of the SegmentedButton control. The items set in this aggregation are used as an interface for the buttons displayed by the control. Only the properties ID, icon, text, enabled and textDirections of the Button control are evaluated. Setting other properties of the button will have no effect. Alternatively, you can use the createButton method to add buttons.
Deprecated as of version 1.28.0. replaced by items aggregation

items 0..n sap.m.SegmentedButtonItem

Aggregation of items to be displayed. The items set in this aggregation are used as an interface for the buttons displayed by the control. The "items" and "buttons" aggregations should NOT be used simultaneously as it causes the control to work incorrectly. Note: If width is supplied in percetange to SegmentedButtonItem instances and the sum of all percentages exeeds 100%, then the buttons display could overlap other elements in the page.

Since: 1.28.


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

selectedButton 0..1 sap.m.Button

A reference to the currently selected button control. By default or if the association is set to false (null, undefined, "", false), the first button will be selected. If the association is set to an invalid value (for example, an ID of a button that does not exist) the selection on the SegmentedButton will be removed.
Deprecated as of version 1.52. replaced by selectedItem association

selectedItem 0..1 sap.m.SegmentedButtonItem

A reference to the currently selected item control.

Since: 1.52.


Events Overview

Event Description
select

Fires when the user selects a button, which returns the ID and button object.

selectionChange

Fires when the user selects an item, which returns the item object.

Since: 1.52.

select

Fires when the user selects a button, which returns the ID and button object.

replaced by <code>selectionChange</code> event
Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
button sap.m.Button

Reference to the button, that has been selected.

id string

ID of the button, which has been selected.

key string

Key of the button, which has been selected. This property is only filled when the control is initiated with the items aggregation.

Since: 1.28.0.

selectionChange

Fires when the user selects an item, which returns the item object.

Since: 1.52.

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

Reference to the item, that has been selected.


Methods Overview

Method Description
addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

addButton

Adds some button to the aggregation buttons.

Since 1.28.0 replaced by <code>items</code> aggregation
addItem

Adds item to items aggregation.

attachSelect

Attaches event handler fnFunction to the select event of this sap.m.SegmentedButton.

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

Fires when the user selects a button, which returns the ID and button object.

Since 1.52 replaced by <code>selectionChange</code> event
attachSelectionChange

Attaches event handler fnFunction to the selectionChange event of this sap.m.SegmentedButton.

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

Fires when the user selects an item, which returns the item object.

bindItems

Binds aggregation items to model data.

See ManagedObject.bindAggregation for a detailed description of the possible properties of oBindingInfo.

bindSelectedKey

Binds property selectedKey to model data.

See ManagedObject.bindProperty for a detailed description of the possible properties of oBindingInfo

createButton

Adds a Button with a text as title, a URI for an icon, enabled and textDirection. Only one is allowed.

destroyButtons

Destroys all the buttons in the aggregation buttons.

Since 1.28.0 replaced by <code>items</code> aggregation
destroyItems

Destroys all the items in the aggregation items.

detachSelect

Detaches event handler fnFunction from the select event of this sap.m.SegmentedButton.

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

Since 1.52 replaced by <code>selectionChange</code> event
detachSelectionChange

Detaches event handler fnFunction from the selectionChange event of this sap.m.SegmentedButton.

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

sap.m.SegmentedButton.extend

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

fireSelect

Fires event select to attached listeners.

Since 1.52 replaced by <code>selectionChange</code> event
fireSelectionChange

Fires event selectionChange to attached listeners.

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.

getButtons

Gets content of aggregation buttons.

The buttons of the SegmentedButton control. The items set in this aggregation are used as an interface for the buttons displayed by the control. Only the properties ID, icon, text, enabled and textDirections of the Button control are evaluated. Setting other properties of the button will have no effect. Alternatively, you can use the createButton method to add buttons.

Since 1.28.0 replaced by <code>items</code> aggregation
getEnabled

Gets current value of property enabled.

Disables all the buttons in the SegmentedButton control. When disabled all the buttons look grey and you cannot focus or click on them.

Default value is true.

getFormDoNotAdjustWidth

SegmentedButton must not be stretched in Form because ResizeHandler is used internally in order to manage the width of the SegmentedButton depending on the container size

getItems

Gets content of aggregation items.

Aggregation of items to be displayed. The items set in this aggregation are used as an interface for the buttons displayed by the control. The "items" and "buttons" aggregations should NOT be used simultaneously as it causes the control to work incorrectly. Note: If width is supplied in percetange to SegmentedButtonItem instances and the sum of all percentages exeeds 100%, then the buttons display could overlap other elements in the page.

sap.m.SegmentedButton.getMetadata

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

getOverflowToolbarConfig

Required by the sap.m.IOverflowToolbarContent interface. Registers invalidation event which is fired when width of the control is changed.

getSelectedButton

ID of the element which is the current target of the association selectedButton, or null.

Since 1.52 replaced by <code>selectedItem</code> association
getSelectedItem

ID of the element which is the current target of the association selectedItem, or null.

getSelectedKey

Gets the selectedKey and is usable only when the control is initiated with the items aggregation.

getWidth

Gets current value of property width.

Defines the width of the SegmentedButton control. If not set, it uses the minimum required width to make all buttons inside of the same size (based on the biggest button).

indexOfButton

Checks for the provided sap.m.Button in the aggregation buttons. and returns its index if found or -1 otherwise.

Since 1.28.0 replaced by <code>items</code> aggregation
indexOfItem

Checks for the provided sap.m.SegmentedButtonItem in the aggregation items. and returns its index if found or -1 otherwise.

insertButton

Inserts a button into the aggregation buttons.

Since 1.28.0 replaced by <code>items</code> aggregation
insertItem

Inserts item into items aggregation.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllButtons

Removes all the controls from the aggregation buttons.

Additionally, it unregisters them from the hosting UIArea.

Since 1.28.0 replaced by <code>items</code> aggregation
removeAllItems

Removes all items from items aggregation

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

removeButton

Removes a button from the aggregation buttons.

Since 1.28.0 replaced by <code>items</code> aggregation
removeItem

Removes an item from items aggregation.

setEnabled

Sets a new value for property enabled.

Disables all the buttons in the SegmentedButton control. When disabled all the buttons look grey and you cannot focus or click on them.

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

Default value is true.

setSelectedButton

Setter for association selectedButton.

setSelectedItem

Setter for association selectedItem.

setSelectedKey

Sets the selectedKey and is usable only when the control is initiated with the items aggregation.

setWidth

Sets a new value for property width.

Defines the width of the SegmentedButton control. If not set, it uses the minimum required width to make all buttons inside of the same size (based on the biggest button).

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

unbindItems

Unbinds aggregation items from model data.

unbindSelectedKey

Unbinds property selectedKey from model data.

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

addButton

Adds some button to the aggregation buttons.

Since 1.28.0 replaced by <code>items</code> aggregation
Param Type DefaultValue Description
oButton sap.m.Button

The button to add; if empty, nothing is inserted

addItem

Adds item to items aggregation.

Param Type DefaultValue Description
oItem sap.m.SegmentedButtonItem

The item to be added

attachSelect

Attaches event handler fnFunction to the select event of this sap.m.SegmentedButton.

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

Fires when the user selects a button, which returns the ID and button object.

Since 1.52 replaced by <code>selectionChange</code> event
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.SegmentedButton itself

attachSelectionChange

Attaches event handler fnFunction to the selectionChange event of this sap.m.SegmentedButton.

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

Fires when the user selects an item, which returns the item object.

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

bindItems

Binds aggregation items to model data.

See ManagedObject.bindAggregation for a detailed description of the possible properties of oBindingInfo.

Param Type DefaultValue Description
oBindingInfo sap.ui.base.ManagedObject.AggregationBindingInfo

The binding information

bindSelectedKey

Binds property selectedKey to model data.

See ManagedObject.bindProperty for a detailed description of the possible properties of oBindingInfo

Param Type DefaultValue Description
oBindingInfo sap.ui.base.ManagedObject.PropertyBindingInfo

The binding information

createButton

Adds a Button with a text as title, a URI for an icon, enabled and textDirection. Only one is allowed.

Param Type DefaultValue Description
sText string

Defines the title text of the newly created Button

sURI sap.ui.core.URI

Icon to be displayed as graphical element within the Button. Density related image will be loaded if image with density awareness name in format [imageName]@[densityValue].[extension] is provided.

bEnabled boolean true

Enables the control. Buttons that are disabled have other colors than enabled ones, depending on custom settings.

sTextDirection sap.ui.core.TextDirection

Element's text directionality with enumerated options

destroyButtons

Destroys all the buttons in the aggregation buttons.

Since 1.28.0 replaced by <code>items</code> aggregation

destroyItems

Destroys all the items in the aggregation items.

detachSelect

Detaches event handler fnFunction from the select event of this sap.m.SegmentedButton.

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

Since 1.52 replaced by <code>selectionChange</code> event
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

detachSelectionChange

Detaches event handler fnFunction from the selectionChange event of this sap.m.SegmentedButton.

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.SegmentedButton.extend

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

fireSelect

Fires event select to attached listeners.

Since 1.52 replaced by <code>selectionChange</code> event
Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

button sap.m.Button

Reference to the button, that has been selected.

id string

ID of the button, which has been selected.

key string

Key of the button, which has been selected. This property is only filled when the control is initiated with the items aggregation.

fireSelectionChange

Fires event selectionChange to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

item sap.m.SegmentedButtonItem

Reference to the item, that has been selected.

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.

getButtons

Gets content of aggregation buttons.

The buttons of the SegmentedButton control. The items set in this aggregation are used as an interface for the buttons displayed by the control. Only the properties ID, icon, text, enabled and textDirections of the Button control are evaluated. Setting other properties of the button will have no effect. Alternatively, you can use the createButton method to add buttons.

Since 1.28.0 replaced by <code>items</code> aggregation

getEnabled

Gets current value of property enabled.

Disables all the buttons in the SegmentedButton control. When disabled all the buttons look grey and you cannot focus or click on them.

Default value is true.

getFormDoNotAdjustWidth

SegmentedButton must not be stretched in Form because ResizeHandler is used internally in order to manage the width of the SegmentedButton depending on the container size

getItems

Gets content of aggregation items.

Aggregation of items to be displayed. The items set in this aggregation are used as an interface for the buttons displayed by the control. The "items" and "buttons" aggregations should NOT be used simultaneously as it causes the control to work incorrectly. Note: If width is supplied in percetange to SegmentedButtonItem instances and the sum of all percentages exeeds 100%, then the buttons display could overlap other elements in the page.

sap.m.SegmentedButton.getMetadata

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

getOverflowToolbarConfig

Required by the sap.m.IOverflowToolbarContent interface. Registers invalidation event which is fired when width of the control is changed.

getSelectedButton

ID of the element which is the current target of the association selectedButton, or null.

Since 1.52 replaced by <code>selectedItem</code> association

getSelectedItem

ID of the element which is the current target of the association selectedItem, or null.

getSelectedKey

Gets the selectedKey and is usable only when the control is initiated with the items aggregation.

getWidth

Gets current value of property width.

Defines the width of the SegmentedButton control. If not set, it uses the minimum required width to make all buttons inside of the same size (based on the biggest button).

indexOfButton

Checks for the provided sap.m.Button in the aggregation buttons. and returns its index if found or -1 otherwise.

Since 1.28.0 replaced by <code>items</code> aggregation
Param Type DefaultValue Description
oButton sap.m.Button

The button whose index is looked for

indexOfItem

Checks for the provided sap.m.SegmentedButtonItem in the aggregation items. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oItem sap.m.SegmentedButtonItem

The item whose index is looked for

insertButton

Inserts a button into the aggregation buttons.

Since 1.28.0 replaced by <code>items</code> aggregation
Param Type DefaultValue Description
oButton sap.m.Button

The button to insert; if empty, nothing is inserted

iIndex int

The 0-based index the button should be inserted at; for a negative value of iIndex, the button is inserted at position 0; for a value greater than the current size of the aggregation, the button is inserted at the last position

insertItem

Inserts item into items aggregation.

Param Type DefaultValue Description
oItem sap.m.SegmentedButtonItem

The item to be inserted

iIndex int

index the item should be inserted at

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllButtons

Removes all the controls from the aggregation buttons.

Additionally, it unregisters them from the hosting UIArea.

Since 1.28.0 replaced by <code>items</code> aggregation

removeAllItems

Removes all items from items aggregation

Param Type DefaultValue Description
bSuppressInvalidate boolean false

If true the control invalidation will be suppressed

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

removeButton

Removes a button from the aggregation buttons.

Since 1.28.0 replaced by <code>items</code> aggregation
Param Type DefaultValue Description
vButton int string sap.m.Button

The button to remove or its index or id

removeItem

Removes an item from items aggregation.

Param Type DefaultValue Description
oItem sap.m.SegmentedButtonItem

The item to be removed

setEnabled

Sets a new value for property enabled.

Disables all the buttons in the SegmentedButton control. When disabled all the buttons look grey and you cannot focus or click on them.

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

setSelectedButton

Setter for association selectedButton.

Param Type DefaultValue Description
vButton string sap.m.Button null undefined

New value for association setSelectedButton An sap.m.Button instance which becomes the new target of this selectedButton association. Alternatively, the ID of an sap.m.Button instance may be given as a string. If the value of null, undefined, or an empty string is provided the first item will be selected.

setSelectedItem

Setter for association selectedItem.

Param Type DefaultValue Description
vItem string sap.m.SegmentedButtonItem null undefined

New value for association setSelectedItem An sap.m.SegmentedButtonItem instance which becomes the new target of this selectedItem association. Alternatively, the ID of an sap.m.SegmentedButtonItem instance may be given as a string. If the value of null, undefined, or an empty string is provided, the first item will be selected.

setSelectedKey

Sets the selectedKey and is usable only when the control is initiated with the items aggregation.

Param Type DefaultValue Description
sKey string

The key of the button to be selected

setWidth

Sets a new value for property width.

Defines the width of the SegmentedButton control. If not set, it uses the minimum required width to make all buttons inside of the same size (based on the biggest button).

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

unbindItems

Unbinds aggregation items from model data.

unbindSelectedKey

Unbinds property selectedKey from model data.