A horizontal control made of multiple buttons, which can display a title or an image.
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.
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 |
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. |
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 |
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. |
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 |
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. |
selectedItem | 0..1 | sap.m.SegmentedButtonItem |
A reference to the currently selected item control. |
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. |
Fires when the user selects a button, which returns the ID and button object.
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. |
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 |
attachSelect |
Attaches event handler When called, the context of the event handler (its 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 When called, the context of the event handler (its 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 |
bindSelectedKey |
Binds property selectedKey to model data. See ManagedObject.bindProperty for a detailed description of the possible properties of |
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 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 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
|
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 |
getFormDoNotAdjustWidth |
|
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 |
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
Since 1.52 replaced by <code>selectedItem</code> association
|
getSelectedItem |
ID of the element which is the current target of the association selectedItem, or |
getSelectedKey |
Gets the |
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
Since 1.28.0 replaced by <code>items</code> aggregation
|
indexOfItem |
Checks for the provided |
insertButton |
Inserts a button into the aggregation buttons.
Since 1.28.0 replaced by <code>items</code> aggregation
|
insertItem |
Inserts item into |
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 |
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 |
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 Default value is |
setSelectedButton |
Setter for association |
setSelectedItem |
Setter for association |
setSelectedKey |
Sets the |
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 |
unbindItems |
Unbinds aggregation items from model data. |
unbindSelectedKey |
Unbinds property selectedKey from model data. |
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 |
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 |
Adds some button to the aggregation buttons.
Param | Type | DefaultValue | Description |
---|---|---|---|
oButton | sap.m.Button |
The button to add; if empty, nothing is inserted |
Adds item to items
aggregation.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.m.SegmentedButtonItem |
The item to be added |
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.
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 |
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 |
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 |
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 |
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 |
Destroys all the buttons in the aggregation buttons.
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.
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 |
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 |
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 |
Fires event select to attached listeners.
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. |
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. |
Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
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.
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
.
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
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.
Required by the sap.m.IOverflowToolbarContent interface. Registers invalidation event which is fired when width of the control is changed.
ID of the element which is the current target of the association selectedButton, or null
.
ID of the element which is the current target of the association selectedItem, or null
.
Gets the selectedKey
and is usable only when the control is initiated with the items
aggregation.
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).
Checks for the provided sap.m.Button
in the aggregation buttons. and returns its index if found or -1 otherwise.
Param | Type | DefaultValue | Description |
---|---|---|---|
oButton | sap.m.Button |
The button whose index is looked for |
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 |
Inserts a button into the aggregation buttons.
Param | Type | DefaultValue | Description |
---|---|---|---|
oButton | sap.m.Button |
The button to insert; if empty, nothing is inserted |
|
iIndex | int |
The |
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 |
Removes all the controls from the aggregation buttons.
Additionally, it unregisters them from the hosting UIArea.
Removes all items from items
aggregation
Param | Type | DefaultValue | Description |
---|---|---|---|
bSuppressInvalidate | boolean | false |
If |
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 |
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 |
Removes a button from the aggregation buttons.
Param | Type | DefaultValue | Description |
---|---|---|---|
vButton | int string sap.m.Button |
The button to remove or its index or id |
Removes an item from items
aggregation.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.m.SegmentedButtonItem |
The item to be removed |
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 |
Setter for association selectedButton
.
Param | Type | DefaultValue | Description |
---|---|---|---|
vButton | string sap.m.Button null undefined |
New value for association |
Setter for association selectedItem
.
Param | Type | DefaultValue | Description |
---|---|---|---|
vItem | string sap.m.SegmentedButtonItem null undefined |
New value for association |
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 |
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 |