Xojo Documentation Xojo Documentation

Check Box Library Icon

Use Check Boxes to let the user choose a preference. A Check Box can be in one of three states: Unchecked, Checked, and Indeterminate. One of the states can be selected by default in the Inspector. Check Boxes should not cause an immediate and obvious action to occur except perhaps to enable or disable other controls.

When the user clicks in a Check Box, it changes from checked to unchecked. The Indeterminate state is a visual indicator only and is set by your code when you want to hide the actual state because it is not known, such as when multiple items are selected. If the Check Box was previously set (by code) to Indeterminate, then when the user clicks in the CheckBox it will cycle between, checked, unchecked and Indeterminate.

The Set Default Value feature changes the Caption.

Refer to CheckBox in the Language Reference for details on all its events, properties and methods.

Below are the commonly used events and properties.

Events

Action

Called when the checkbox is pressed or the value is changed by code.

Properties

Caption

Used to set or change the caption text for the check box.

VisualState

Used to get or set the state (unchecked, checked or indeterminate) of the checkbox. Changing VisualState also changes the Value property (check or indeterminate set Value to True, unchecked sets Value to False). Use the VisualStates enumeration (VisualStates.Unchecked, VisualStates.Checked, VisualStates.Indeterminate) to set or check the state rather than directly using Integer values.

Value

True if the check box is checked (or indeterminate), False if it is not checked.

Handling Focus

When a CheckBox gets the focus, a marquee surrounds the CheckBox label. Pressing the Spacebar while the CheckBox has the focus toggles the control between its unchecked and checked states.

Usage

Check Box on a Window

You will typically have code in the Action event handler to looked at the Value or VisualState of the CheckBox and then take an appropriate action. For example, this code enables or disables a TextField:

EmailField.Enabled = Me.Value

Use the VisualState property to check for situations where Indeterminate might be a value.

Select Case Me.VisualState
Case CheckBox.VisualStates.Checked
EmailField.Enabled = True
Case CheckBox.VisualStates.Unchecked
EmailField.Enabled = False
Case CheckBox.VisualStates.Indeterminate
// Do not change EmailField
End Select

See Also

CheckBox class; UserGuide:Desktop Radio Button topic