Class sap.m.CheckBoxModule: sap/m/CheckBox

extends Control

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 2 states - checked and unchecked. There is no third state for 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.

Constructor Summary
new sap.m.CheckBox(sId?, mSettings?)Constructor for a new CheckBox.
Event Summary
select(oControlEvent)Event is triggered when the control status is changed by the user by selecting or deselecting the checkbox.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.m.CheckBox.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.CheckBox with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.CheckBox.getMetadata()Returns a metadata object for class sap.m.CheckBox.
addAriaDescribedBy(vAriaDescribedBy)Adds some ariaDescribedBy into the association ariaDescribedBy.
addAriaLabelledBy(vAriaLabelledBy)Adds some ariaLabelledBy into the association ariaLabelledBy.
attachSelect(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the select event of this sap.m.CheckBox.
detachSelect(fnFunction, oListener)Detaches event handler fnFunction from the select event of this sap.m.CheckBox.
fireSelect(mParameters?)Fires event select to attached listeners.
getActiveHandling()Gets current value of property activeHandling.
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.
getEditable()Gets current value of property editable.
getEnabled()Gets current value of property enabled.
getName()Gets current value of property name.
getSelected()Gets current value of property selected.
getTabIndex()Returns the CheckBox`s tab index.
getText()Gets current value of property text.
getTextAlign()Gets current value of property textAlign.
getTextDirection()Gets current value of property textDirection.
getUseEntireWidth()Gets current value of property useEntireWidth.
getValueState()Gets current value of property valueState.
getWidth()Gets current value of property width.
getWrapping()Gets current value of property wrapping.
removeAllAriaDescribedBy()Removes all the controls in the association named ariaDescribedBy.
removeAllAriaLabelledBy()Removes all the controls in the association named ariaLabelledBy.
removeAriaDescribedBy(vAriaDescribedBy)Removes an ariaDescribedBy from the association named ariaDescribedBy.
removeAriaLabelledBy(vAriaLabelledBy)Removes an ariaLabelledBy from the association named ariaLabelledBy.
setActiveHandling(bActiveHandling)Sets a new value for property activeHandling.
setDisplayOnly(bDisplayOnly)Sets a new value for property displayOnly.
setEditable(bEditable)Sets a new value for property editable.
setEnabled(bEnabled)Sets a new value for property enabled.
setName(sName)Sets a new value for property name.
setSelected(bSelected)Sets a new value for property selected.
setTabIndex(iTabIndex)Sets the tab index of the control
setText(sText)Sets a new value for property text.
setTextAlign(sTextAlign)Sets a new value for property textAlign.
setTextDirection(sTextDirection)Sets a new value for property textDirection.
setUseEntireWidth(bUseEntireWidth)Sets a new value for property useEntireWidth.
setValueState(sValueState)Sets a new value for property valueState.
setWidth(sWidth)Sets a new value for property width.
setWrapping(bWrapping)Sets a new value for property wrapping.
Constructor Detail
new sap.m.CheckBox(sId?, mSettings?)

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 for a general description of the syntax of the settings object.

The supported settings are:

  • Properties

  • Aggregations

    • Associations

    • Events

      • select : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]

    In addition, all settings applicable to the base type sap.ui.core.Control can be used as well.

    Parameters:
    stringsId?The ID for the new control, generated automatically if no ID is given
    objectmSettings?The Initial settings for the new control
    Event Detail
    select(oControlEvent)
    Event is triggered when the control status is changed by the user by selecting or deselecting the checkbox.
    Parameters:
    sap.ui.base.EventoControlEvent
    sap.ui.base.EventProvideroControlEvent.getSource
    objectoControlEvent.getParameters
    booleanoControlEvent.getParameters.selectedChecks whether the CheckBox is marked or not .
    Method Detail
    sap.m.CheckBox.extend(sClassName, oClassInfo?, FNMetaImpl?): function

    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.

    Parameters:
    stringsClassNameName of the class being created
    objectoClassInfo?Object literal with information about the class
    functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
    Returns:
    functionCreated class / constructor function
    sap.m.CheckBox.getMetadata(): sap.ui.base.Metadata
    Returns a metadata object for class sap.m.CheckBox.
    Returns:
    sap.ui.base.MetadataMetadata object describing this class
    addAriaDescribedBy(vAriaDescribedBy): sap.m.CheckBox
    Adds some ariaDescribedBy into the association ariaDescribedBy.
    Parameters:
    sap.ui.core.ID|sap.ui.core.ControlvAriaDescribedByThe ariaDescribedBy to add; if empty, nothing is inserted
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    addAriaLabelledBy(vAriaLabelledBy): sap.m.CheckBox
    Adds some ariaLabelledBy into the association ariaLabelledBy.
    Parameters:
    sap.ui.core.ID|sap.ui.core.ControlvAriaLabelledByThe ariaLabelledBy to add; if empty, nothing is inserted
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    attachSelect(oData?, fnFunction, oListener?): sap.m.CheckBox

    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.

    Parameters:
    objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
    functionfnFunctionThe function to be called when the event occurs
    objectoListener?Context object to call the event handler with. Defaults to this sap.m.CheckBox itself
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    detachSelect(fnFunction, oListener): sap.m.CheckBox

    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.

    Parameters:
    functionfnFunctionThe function to be called, when the event occurs
    objectoListenerContext object on which the given function had to be called
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    fireSelect(mParameters?): sap.m.CheckBox
    Fires event select to attached listeners.
    Parameters:
    objectmParameters?Parameters to pass along with the event
    booleanmParameters.selected?Checks whether the CheckBox is marked or not .
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    getAccessibilityInfo(): Object
    Returns:
    ObjectThe sap.m.CheckBox accessibility information
    See:
    sap.ui.core.Control#getAccessibilityInfo
    getActiveHandling(): boolean

    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:
    booleanValue of property activeHandling
    getAriaDescribedBy(): sap.ui.core.ID[]
    Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.
    Returns:
    sap.ui.core.ID[]
    getAriaLabelledBy(): sap.ui.core.ID[]
    Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
    Returns:
    sap.ui.core.ID[]
    getDisplayOnly(): boolean

    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.

    Returns:
    booleanValue of property displayOnly
    Since:
    1.54
    getEditable(): boolean

    Gets current value of property editable.

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

    Default value is true.

    Returns:
    booleanValue of property editable
    Since:
    1.25
    getEnabled(): boolean

    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.

    Returns:
    booleanValue of property enabled
    getName(): string

    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.

    Returns:
    stringValue of property name
    getSelected(): boolean

    Gets current value of property selected.

    Stores the state of the checkbox whether it is selected or not.

    Default value is false.

    Returns:
    booleanValue of property selected
    getTabIndex(): int
    Returns the CheckBox`s tab index.
    Returns:
    intiTabIndex for Checkbox
    Since:
    1.22
    getText(): string

    Gets current value of property text.

    Defines the text displayed next to the checkbox

    Returns:
    stringValue of property text
    getTextAlign(): sap.ui.core.TextAlign

    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.

    Returns:
    sap.ui.core.TextAlignValue of property textAlign
    getTextDirection(): sap.ui.core.TextDirection

    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.

    Returns:
    sap.ui.core.TextDirectionValue of property textDirection
    getUseEntireWidth(): boolean

    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.

    Returns:
    booleanValue of property useEntireWidth
    Since:
    1.52
    getValueState(): sap.ui.core.ValueState

    Gets current value of property valueState.

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

    Default value is None.

    Returns:
    sap.ui.core.ValueStateValue of property valueState
    Since:
    1.38
    getWidth(): sap.ui.core.CSSSize

    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.

    Returns:
    sap.ui.core.CSSSizeValue of property width
    getWrapping(): boolean

    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.

    Returns:
    booleanValue of property wrapping
    Since:
    1.54
    removeAllAriaDescribedBy(): sap.ui.core.ID[]
    Removes all the controls in the association named ariaDescribedBy.
    Returns:
    sap.ui.core.ID[]An array of the removed elements (might be empty)
    removeAllAriaLabelledBy(): sap.ui.core.ID[]
    Removes all the controls in the association named ariaLabelledBy.
    Returns:
    sap.ui.core.ID[]An array of the removed elements (might be empty)
    removeAriaDescribedBy(vAriaDescribedBy): sap.ui.core.ID
    Removes an ariaDescribedBy from the association named ariaDescribedBy.
    Parameters:
    int|sap.ui.core.ID|sap.ui.core.ControlvAriaDescribedByThe ariaDescribedBy to be removed or its index or ID
    Returns:
    sap.ui.core.IDThe removed ariaDescribedBy or null
    removeAriaLabelledBy(vAriaLabelledBy): sap.ui.core.ID
    Removes an ariaLabelledBy from the association named ariaLabelledBy.
    Parameters:
    int|sap.ui.core.ID|sap.ui.core.ControlvAriaLabelledByThe ariaLabelledBy to be removed or its index or ID
    Returns:
    sap.ui.core.IDThe removed ariaLabelledBy or null
    setActiveHandling(bActiveHandling): sap.m.CheckBox

    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.

    Parameters:
    booleanbActiveHandlingNew value for property activeHandling
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    setDisplayOnly(bDisplayOnly): sap.m.CheckBox

    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.

    Parameters:
    booleanbDisplayOnlyNew value for property displayOnly
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    Since:
    1.54
    setEditable(bEditable): sap.m.CheckBox

    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.

    Parameters:
    booleanbEditableNew value for property editable
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    Since:
    1.25
    setEnabled(bEnabled): sap.m.CheckBox

    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.

    Parameters:
    booleanbEnabledNew value for property enabled
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    setName(sName): sap.m.CheckBox

    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.

    Parameters:
    stringsNameNew value for property name
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    setSelected(bSelected): sap.m.CheckBox

    Sets a new value for property selected.

    Stores the state of the checkbox whether it is selected or not.

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

    Default value is false.

    Parameters:
    booleanbSelectedNew value for property selected
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    setTabIndex(iTabIndex): sap.m.CheckBox
    Sets the tab index of the control
    Parameters:
    intiTabIndexThe tab index should be greater than or equal -1
    Returns:
    sap.m.CheckBoxThe sap.m.CheckBox instance
    Since:
    1.16
    setText(sText): sap.m.CheckBox

    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.

    Parameters:
    stringsTextNew value for property text
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    setTextAlign(sTextAlign): sap.m.CheckBox

    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.

    Parameters:
    sap.ui.core.TextAlignsTextAlignNew value for property textAlign
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    setTextDirection(sTextDirection): sap.m.CheckBox

    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.

    Parameters:
    sap.ui.core.TextDirectionsTextDirectionNew value for property textDirection
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    setUseEntireWidth(bUseEntireWidth): sap.m.CheckBox

    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.

    Parameters:
    booleanbUseEntireWidthNew value for property useEntireWidth
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    Since:
    1.52
    setValueState(sValueState): sap.m.CheckBox

    Sets a new value for property valueState.

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

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

    Default value is None.

    Parameters:
    sap.ui.core.ValueStatesValueStateNew value for property valueState
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    Since:
    1.38
    setWidth(sWidth): sap.m.CheckBox

    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.

    Parameters:
    sap.ui.core.CSSSizesWidthNew value for property width
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    setWrapping(bWrapping): sap.m.CheckBox

    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.

    Parameters:
    booleanbWrappingNew value for property wrapping
    Returns:
    sap.m.CheckBoxReference to this in order to allow method chaining
    Since:
    1.54