UserGuide

Desktop Check Box

From Xojo Documentation

You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!
Check Box Library Icon

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

When the user clicks in a Checkbox, 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 Checkbox 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 DesktopCheckBox in the Language Reference for details on all its events, properties and methods.

Below are the commonly used events and properties.

Events

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

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 ValueChanged 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 DesktopCheckBox.VisualStates.Checked
EmailField.Enabled = True
Case DesktopCheckBox.VisualStates.Unchecked
EmailField.Enabled = False
Case DesktopCheckBox.VisualStates.Indeterminate
// Do not change EmailField
End Select

See Also

DesktopCheckBox class