Allows the user to set a binary value, such as true/false or yes/no for an item.
The CheckBox
control consists of a box and a label that describes its purpose. If it's checked, an indicator is displayed inside the box.
To select/deselect the CheckBox
, the user has to click or tap the square box or its label. Clicking or tapping toggles the CheckBox
between checked and unchecked state. The CheckBox
control only has 3 states - checked, unchecked and partially selected.
You can set the width of the element containing the box and the label manually with the use of the width
property. If the text exceeds the available width, it is truncated.
Note: When useEntireWidth
property is set to true
, the value of the width
property is applied to the control as a whole (box and label). If useEntireWidth
is set to false
, the width
is applied to the label only.
The touchable area for toggling the CheckBox
ends where the text ends.
If the width allows more space than the text requires, white space is added. The text can be positioned manually in this space using the textAlign
property.
Note: Keep in mind that setting the textAlign
property to Right
can result in a large amount of white space between the box and the text.
You can disable the CheckBox
by setting the enabled
property to false
, or use the CheckBox
in read-only mode by setting the editable
property to false.
Note: Disabled and read-only states shouldn't be used together.
Constructor for a new CheckBox
.
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.CheckBox(sId?, mSettings?)
Param | Type | Default Value | Description |
---|---|---|---|
sId? | string | The ID for the new control, generated automatically if no ID is given |
|
mSettings? | object | The Initial settings for the new control |
Name | Type | Default Value | Description |
---|---|---|---|
activeHandling | boolean | true | Flag to switch on activeHandling, when it is switched off, there will be no visual changes on active state. Default value is 'true' Visibility: public |
displayOnly | boolean | false | Determines whether the When set to
|
editable | boolean | true | Specifies whether the user shall be allowed to edit the state of the checkbox |
enabled | boolean | true | Disables the Checkbox. Disabled controls are not interactive and are rendered differently according to the theme. Visibility: public |
name | string | The 'name' property to be used in the HTML code, for example for HTML forms that send data to the server via submit. Visibility: public |
|
partiallySelected | boolean | false | Determines whether the Note: This property leads only to visual change of the checkbox and the state cannot be achieved by user interaction. The visual state depends on the value of the
Since: 1.58.Visibility: public |
selected | boolean | false | Determines whether the When this property is set to |
text | string | Defines the text displayed next to the checkbox Visibility: public |
|
textAlign | sap.ui.core.TextAlign | Begin | Aligns the text of the checkbox. Available alignment settings are "Begin", "Center", "End", "Left", and "Right". Visibility: public |
textDirection | sap.ui.core.TextDirection | Inherit | Options for the text direction are RTL and LTR. Alternatively, the control can inherit the text direction from its parent container. Visibility: public |
useEntireWidth | boolean | false | Indicates if the given width will be applied to the control as a whole or to its label only. Note: by default the width is set to the label |
valueState | sap.ui.core.ValueState | None | Accepts the core enumeration ValueState.type that supports 'None', 'Error', 'Warning', 'Success' and 'Information'. |
valueStateText | string | Defines the text that appears in the tooltip of the |
|
width | sap.ui.core.CSSSize | empty string | Determines the total width of the control or the width of its label only, depending on the value of Note: When |
wrapping | boolean | false | Determines whether the label's text is wrapped. When set to |
Default Aggregation:
Name | Cardinality | Type | Description |
---|---|---|---|
_label | 0..1 | sap.m.Label |
The label that represents the text of the checkbox control |
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). |
Event | Description |
---|---|
select |
Event is triggered when the control status is changed by the user by selecting or deselecting the checkbox. |
Method | Description |
---|---|
addAriaDescribedBy |
Adds some ariaDescribedBy into the association ariaDescribedBy. |
addAriaLabelledBy |
Adds some ariaLabelledBy into the association ariaLabelledBy. |
attachSelect |
Attaches event handler When called, the context of the event handler (its Event is triggered when the control status is changed by the user by selecting or deselecting the checkbox. |
detachSelect |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.m.CheckBox.extend |
Creates a new subclass of class sap.m.CheckBox with name
|
fireSelect |
Fires event select to attached listeners. |
getAccessibilityInfo |
References:
|
getActiveHandling |
Gets current value of property activeHandling. Flag to switch on activeHandling, when it is switched off, there will be no visual changes on active state. Default value is 'true' Default value is |
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. |
getDisplayOnly |
Gets current value of property displayOnly. Determines whether the When set to
Default value is |
getEditable |
Gets current value of property editable. Specifies whether the user shall be allowed to edit the state of the checkbox Default value is |
getEnabled |
Gets current value of property enabled. Disables the Checkbox. Disabled controls are not interactive and are rendered differently according to the theme. Default value is |
sap.m.CheckBox.getMetadata |
Returns a metadata object for class sap.m.CheckBox. |
getName |
Gets current value of property name. The 'name' property to be used in the HTML code, for example for HTML forms that send data to the server via submit. |
getPartiallySelected |
Gets current value of property partiallySelected. Determines whether the Note: This property leads only to visual change of the checkbox and the state cannot be achieved by user interaction. The visual state depends on the value of the
Default value is |
getSelected |
Gets current value of property selected. Determines whether the When this property is set to Default value is |
getTabIndex |
Returns the CheckBox`s tab index. |
getText |
Gets current value of property text. Defines the text displayed next to the checkbox |
getTextAlign |
Gets current value of property textAlign. Aligns the text of the checkbox. Available alignment settings are "Begin", "Center", "End", "Left", and "Right". Default value is |
getTextDirection |
Gets current value of property textDirection. Options for the text direction are RTL and LTR. Alternatively, the control can inherit the text direction from its parent container. Default value is |
getUseEntireWidth |
Gets current value of property useEntireWidth. Indicates if the given width will be applied to the control as a whole or to its label only. Note: by default the width is set to the label Default value is |
getValueState |
Gets current value of property valueState. Accepts the core enumeration ValueState.type that supports 'None', 'Error', 'Warning', 'Success' and 'Information'. Default value is |
getWidth |
Gets current value of property width. Determines the total width of the control or the width of its label only, depending on the value of Note: When Default value is |
getWrapping |
Gets current value of property wrapping. Determines whether the label's text is wrapped. When set to Default value is |
removeAllAriaDescribedBy |
Removes all the controls in the association named ariaDescribedBy. |
removeAllAriaLabelledBy |
Removes all the controls in the association named ariaLabelledBy. |
removeAriaDescribedBy |
Removes an ariaDescribedBy from the association named ariaDescribedBy. |
removeAriaLabelledBy |
Removes an ariaLabelledBy from the association named ariaLabelledBy. |
setActiveHandling |
Sets a new value for property activeHandling. Flag to switch on activeHandling, when it is switched off, there will be no visual changes on active state. Default value is 'true' When called with a value of Default value is |
setDisplayOnly |
Sets a new value for property displayOnly. Determines whether the When set to
When called with a value of Default value is |
setEditable |
Sets a new value for property editable. Specifies whether the user shall be allowed to edit the state of the checkbox When called with a value of Default value is |
setEnabled |
Sets a new value for property enabled. Disables the Checkbox. Disabled controls are not interactive and are rendered differently according to the theme. When called with a value of Default value is |
setName |
Sets a new value for property name. The 'name' property to be used in the HTML code, for example for HTML forms that send data to the server via submit. When called with a value of |
setPartiallySelected |
Sets a new value for property partiallySelected. Determines whether the Note: This property leads only to visual change of the checkbox and the state cannot be achieved by user interaction. The visual state depends on the value of the
When called with a value of Default value is |
setSelected |
Sets a new value for property selected. Determines whether the When this property is set to When called with a value of Default value is |
setTabIndex |
Sets the tab index of the control |
setText |
Sets a new value for property text. Defines the text displayed next to the checkbox When called with a value of |
setTextAlign |
Sets a new value for property textAlign. Aligns the text of the checkbox. Available alignment settings are "Begin", "Center", "End", "Left", and "Right". When called with a value of Default value is |
setTextDirection |
Sets a new value for property textDirection. Options for the text direction are RTL and LTR. Alternatively, the control can inherit the text direction from its parent container. When called with a value of Default value is |
setUseEntireWidth |
Sets a new value for property useEntireWidth. Indicates if the given width will be applied to the control as a whole or to its label only. Note: by default the width is set to the label When called with a value of Default value is |
setValueState |
Sets a new value for property valueState. Accepts the core enumeration ValueState.type that supports 'None', 'Error', 'Warning', 'Success' and 'Information'. When called with a value of Default value is |
setWidth |
Sets a new value for property width. Determines the total width of the control or the width of its label only, depending on the value of Note: When When called with a value of Default value is |
setWrapping |
Sets a new value for property wrapping. Determines whether the label's text is wrapped. When set to When called with a value of Default value is |
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 |
Attaches event handler fnFunction
to the select event of this sap.m.CheckBox
.
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.CheckBox
itself.
Event is triggered when the control status is changed by the user by selecting or deselecting the checkbox.
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 |
Detaches event handler fnFunction
from the select event of this sap.m.CheckBox
.
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.CheckBox 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 |
|
selected | boolean |
Checks whether the CheckBox is marked or not . |
Gets current value of property activeHandling.
Flag to switch on activeHandling, when it is switched off, there will be no visual changes on active state. Default value is 'true'
Default value is true
.
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 current value of property displayOnly.
Determines whether the CheckBox
is in display only state.
When set to true
, the CheckBox
is not interactive, not editable, not focusable and not in the tab chain. This setting is used for forms in review mode.
enabled
is set to false
this property has no effect.
Default value is false
.
Gets current value of property editable.
Specifies whether the user shall be allowed to edit the state of the checkbox
Default value is true
.
Gets current value of property enabled.
Disables the Checkbox. Disabled controls are not interactive and are rendered differently according to the theme.
Default value is true
.
Gets current value of property name.
The 'name' property to be used in the HTML code, for example for HTML forms that send data to the server via submit.
Gets current value of property partiallySelected.
Determines whether the CheckBox
is displayed as partially selected.
Note: This property leads only to visual change of the checkbox and the state cannot be achieved by user interaction. The visual state depends on the value of the selected
property:
selected
= true
and partiallySelected
= true
, the control is displayed as partially selectedselected
= true
and partiallySelected
= false
, the control is displayed as selectedselected
= false
, the control is displayed as not selected regardless of what is set for partiallySelected
Default value is false
.
Gets current value of property selected.
Determines whether the CheckBox
is selected (checked).
When this property is set to true
, the control is displayed as selected, unless the value of the partiallySelected
property is also set to true
. In this case, the control is displayed as partially selected.
Default value is false
.
Gets current value of property textAlign.
Aligns the text of the checkbox. Available alignment settings are "Begin", "Center", "End", "Left", and "Right".
Default value is Begin
.
Gets current value of property textDirection.
Options for the text direction are RTL and LTR. Alternatively, the control can inherit the text direction from its parent container.
Default value is Inherit
.
Gets current value of property useEntireWidth.
Indicates if the given width will be applied to the control as a whole or to its label only.
Note: by default the width is set to the label
Default value is false
.
Gets current value of property valueState.
Accepts the core enumeration ValueState.type that supports 'None', 'Error', 'Warning', 'Success' and 'Information'.
Default value is None
.
Gets current value of property width.
Determines the total width of the control or the width of its label only, depending on the value of useEntireWidth
.
Note: When useEntireWidth
is set to true
, width
is applied to the control as a whole (checkbox and label). Otherwise, width
is applied to the label only.
Default value is empty string
.
Gets current value of property wrapping.
Determines whether the label's text is wrapped.
When set to false
(default), the label's text is truncated with ellipsis at the end.
Default value is false
.
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 |
Sets a new value for property activeHandling.
Flag to switch on activeHandling, when it is switched off, there will be no visual changes on active state. Default value is 'true'
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 |
---|---|---|---|
bActiveHandling | boolean | true |
New value for property |
Sets a new value for property displayOnly.
Determines whether the CheckBox
is in display only state.
When set to true
, the CheckBox
is not interactive, not editable, not focusable and not in the tab chain. This setting is used for forms in review mode.
enabled
is set to false
this property has no effect.
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 |
---|---|---|---|
bDisplayOnly | boolean | false |
New value for property |
Sets a new value for property editable.
Specifies whether the user shall be allowed to edit the state of the checkbox
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 |
---|---|---|---|
bEditable | boolean | true |
New value for property |
Sets a new value for property enabled.
Disables the Checkbox. Disabled controls are not interactive and are rendered differently according to the theme.
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 |
Sets a new value for property name.
The 'name' property to be used in the HTML code, for example for HTML forms that send data to the server via submit.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
New value for property |
Sets a new value for property partiallySelected.
Determines whether the CheckBox
is displayed as partially selected.
Note: This property leads only to visual change of the checkbox and the state cannot be achieved by user interaction. The visual state depends on the value of the selected
property:
selected
= true
and partiallySelected
= true
, the control is displayed as partially selectedselected
= true
and partiallySelected
= false
, the control is displayed as selectedselected
= false
, the control is displayed as not selected regardless of what is set for partiallySelected
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 |
---|---|---|---|
bPartiallySelected | boolean | false |
New value for property |
Sets a new value for property selected.
Determines whether the CheckBox
is selected (checked).
When this property is set to true
, the control is displayed as selected, unless the value of the partiallySelected
property is also set to true
. In this case, the control is displayed as partially selected.
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 |
---|---|---|---|
bSelected | boolean | false |
New value for property |
Sets the tab index of the control
Param | Type | DefaultValue | Description |
---|---|---|---|
iTabIndex | int |
The tab index should be greater than or equal -1 |
Sets a new value for property text.
Defines the text displayed next to the checkbox
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sText | string |
New value for property |
Sets a new value for property textAlign.
Aligns the text of the checkbox. Available alignment settings are "Begin", "Center", "End", "Left", and "Right".
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is Begin
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sTextAlign | sap.ui.core.TextAlign | Begin |
New value for property |
Sets a new value for property textDirection.
Options for the text direction are RTL and LTR. Alternatively, the control can inherit the text direction from its parent container.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is Inherit
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sTextDirection | sap.ui.core.TextDirection | Inherit |
New value for property |
Sets a new value for property useEntireWidth.
Indicates if the given width will be applied to the control as a whole or to its label only.
Note: by default the width is set to the label
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 |
---|---|---|---|
bUseEntireWidth | boolean | false |
New value for property |
Sets a new value for property valueState.
Accepts the core enumeration ValueState.type that supports 'None', 'Error', 'Warning', 'Success' and 'Information'.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is None
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sValueState | sap.ui.core.ValueState | None |
New value for property |
Sets a new value for property width.
Determines the total width of the control or the width of its label only, depending on the value of useEntireWidth
.
Note: When useEntireWidth
is set to true
, width
is applied to the control as a whole (checkbox and label). Otherwise, width
is applied to the label only.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is empty string
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sWidth | sap.ui.core.CSSSize | '' |
New value for property |
Sets a new value for property wrapping.
Determines whether the label's text is wrapped.
When set to false
(default), the label's text is truncated with ellipsis at the end.
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 |
---|---|---|---|
bWrapping | boolean | false |
New value for property |