CheckBox

Wire name checkbox

An independent on/off control, optionally with a third mixed state.

new checkbox caption="Word wrap" checked

---

Properties

Property	Type	Default	Meaning
action	action	—	Optional command dispatched on toggle.
caption	string	—	Checkbox label text.
checked	flag	—	Checked state (tri-capable: on/off/mixed).
tristate	flag	false	Allow clicking through the mixed state.
wrap	flag	false	Word-wrap the label.

Plus the common properties.

Events

command — The command named by action= was activated. Raised only when action= is set, and before the toggle event, so a client may act on either. Carries the command rather than the trinket, because a command is what an application binds to and the same one may be reachable from several places.

Field	Type	Meaning
action	word	The command ID from action=.

toggle — The checked state changed.

Field	Type	Meaning
trinket	uint	The checkbox's object ID.
checked	flag	The new state: set, unset, or indeterminate on a tristate box.

command appears only when action= is set, and arrives before toggle.

The three states

checked is a tri-capable flag, so all three states have a spelling:

new checkbox caption="Bold" checked      # on
new checkbox caption="Bold" !checked     # off
new checkbox caption="Bold" ?checked     # mixed

checked=true / false / mixed also parse, for tooling that generates properties rather than writing them.

?checked sets the mixed state whether or not tristate is set — the property says what the box is. tristate says what the user can reach by clicking, and it changes the cycle:

tristate	Clicking walks
unset (default)	on → off → on → …
set	on → mixed → off → on → …

So a two-state box can still be put into the mixed state by the application — showing "some of the selection is bold" — and the user's next click takes it out and never back. That is usually what you want: mixed is a report, not a choice.

Reading the event

toggle carries checked as a flag with three values, not a boolean:

ui.Checkbox("bold").OnToggle(func(s protocol.FlagState) {
	switch s {
	case protocol.FlagTrue:          // on
	case protocol.FlagFalse:         // off
	case protocol.FlagIndeterminate: // mixed
	}
})

A client that treats the flag as a boolean will read mixed as off. On a non-tristate box that is harmless, since the user cannot reach mixed; on a tristate one it silently loses a state.

Keys and mouse

The same as Button: Space and Return toggle, a click toggles, dragging off a held checkbox cancels. It takes focus by Tab and by click.

Behavior

Independent, always. Checkboxes never exclude one another, however they are arranged. For mutual exclusion use RadioButton, which has an explicit group.

Wrapping. wrap word-wraps the label, the same as on a Label — height-for-width and all.

Accessibility. Role Checkbox, with the checked state reported including mixed.

See also

RadioButton · Button · Common Properties · Events