class sap.m.CheckBox

Control sample: sap.m.CheckBox
Visiblity: public
UX Guidelines: Check Box
Implements: sap.ui.core.IFormContentsap.ui.core.ISemanticFormContent
Available since: N/A
Module: sap/m/CheckBox
Application Component: CA-UI5-CTR

Allows the user to set a binary value, such as true/false or yes/no for an item.

Overview

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.

Usage

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.

This control can be a drag source.

Constructor

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


Properties

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

When the property enabled is set to false this property has no effect.

Since: 1.54.

Visibility: public
editable boolean true

Specifies whether the user shall be allowed to edit the state of the checkbox

Since: 1.25.

Visibility: public
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 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:

  • If selected = true and partiallySelected = true, the control is displayed as partially selected
  • If selected = true and partiallySelected = false, the control is displayed as selected
  • If selected = false, the control is displayed as not selected regardless of what is set for partiallySelected


Since: 1.58.

Visibility: public
selected boolean false

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.

Visibility: public
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

Since: 1.52.

Visibility: public
valueState sap.ui.core.ValueState None

Accepts the core enumeration ValueState.type that supports 'None', 'Error', 'Warning', 'Success' and 'Information'.

Since: 1.38.

Visibility: public
valueStateText string

Defines the text that appears in the tooltip of the CheckBox. If this is not specified, a default text is shown from the resource bundle.

Since: 1.74.

Visibility: hidden
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 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.

Visibility: public
wrapping boolean false

Determines whether the label's text is wrapped.

When set to false (default), the label's text is truncated with ellipsis at the end.

Since: 1.54.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
_label 0..1 sap.m.Label

The label that represents the text of the checkbox control


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


Events Overview

Event Description
select

Event is triggered when the control status is changed by the user by selecting or deselecting the checkbox.

select

Event is triggered when the control status is changed by the user by selecting or deselecting the checkbox.

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

Checks whether the CheckBox is marked or not .


Methods Overview

Method Description
addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

attachSelect

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.

detachSelect

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.

sap.m.CheckBox.extend

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.

fireSelect

Fires event select to attached listeners.

getAccessibilityInfo

References:

  • sap.ui.core.Control#getAccessibilityInfo

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

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

When the property enabled is set to false this property has no effect.

Default value is false.

getEditable

Gets current value of property editable.

Specifies whether the user shall be allowed to edit the state of the checkbox

Default value is true.

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

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

  • If selected = true and partiallySelected = true, the control is displayed as partially selected
  • If selected = true and partiallySelected = false, the control is displayed as selected
  • If selected = false, the control is displayed as not selected regardless of what is set for partiallySelected

Default value is false.

getSelected

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.

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

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

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

getValueState

Gets current value of property valueState.

Accepts the core enumeration ValueState.type that supports 'None', 'Error', 'Warning', 'Success' and 'Information'.

Default value is None.

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

getWrapping

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.

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 null or undefined, the default value of the property will be restored.

Default value is true.

setDisplayOnly

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.

When the property 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.

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 null or undefined, the default value of the property will be restored.

Default value is true.

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 null or undefined, the default value of the property will be restored.

Default value is true.

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 null or undefined, the default value of the property will be restored.

setPartiallySelected

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:

  • If selected = true and partiallySelected = true, the control is displayed as partially selected
  • If selected = true and partiallySelected = false, the control is displayed as selected
  • If selected = 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.

setSelected

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.

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 null or undefined, the default value of the property will be restored.

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 null or undefined, the default value of the property will be restored.

Default value is Begin.

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 null or undefined, the default value of the property will be restored.

Default value is Inherit.

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 null or undefined, the default value of the property will be restored.

Default value is false.

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 null or undefined, the default value of the property will be restored.

Default value is None.

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

setWrapping

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.

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

attachSelect

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 sap.m.CheckBox itself

detachSelect

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

sap.m.CheckBox.extend

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

fireSelect

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 .

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

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

When the property enabled is set to false this property has no effect.

Default value is false.

getEditable

Gets current value of property editable.

Specifies whether the user shall be allowed to edit the state of the checkbox

Default value is true.

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

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

Default value is false.

getSelected

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.

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

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

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

getValueState

Gets current value of property valueState.

Accepts the core enumeration ValueState.type that supports 'None', 'Error', 'Warning', 'Success' and 'Information'.

Default value is None.

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

getWrapping

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.

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.

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

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 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 activeHandling

setDisplayOnly

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.

When the property 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 displayOnly

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 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 editable

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

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 null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sName string

New value for property name

setPartiallySelected

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:

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 partiallySelected

setSelected

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 selected

setTabIndex

Sets the tab index of the control

Param Type DefaultValue Description
iTabIndex int

The tab index should be greater than or equal -1

setText

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 text

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 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 textAlign

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 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 textDirection

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 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 useEntireWidth

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 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 valueState

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 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 width

setWrapping

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 wrapping