ZCheckBox

• 

  Checkbox with text “CheckBox”

• 

  in focused state

• 

  in disabled state

A checkbox allows users to select or deselect an option. In contrast to radiobuttons each checkbox has an independent state. The state can be toggled by using Space or if set by using a keyboard mnemonic.

The key to toggle the checkbox is usually shown highlighted when set using markup to set its text.

A checkbox is either checked or unchecked. If the tristate attribute is enabled it additionally supports a third partially checked state. The partially checked state is commonly used when a checkbox represents a summary of multiple states and it’s represented states contain both checked and unchecked values. A checkbox shown as partially checked by convention indicates that none of the represented substates will be altered.

• 

  checked state

• 

  partially checked state

Example

Tui::ZCheckBox *checkbox = new Tui::ZCheckBox(Tui::withMarkup, "C<m>h</m>eckbox", dialog);
layout->addWidget(checkbox);

QObject::connect(checkbox, &Tui::ZCheckBox::stateChanged, [](Qt::CheckState state) { /* ... */ });

Keyboard Usage

Key	Result
Space	Activate the button
Alt + (setup mnemonic)	Activate the button
(setup shortcut)	Activate the button

Behavior

Checkboxes by default accept focus, are one cell high and have a expanding vertical layout policy. The size request of a checkbox is the length of the text plus 5 cells plus the contents margins.

When the user toggles the state of the checkbox (e.g. using the Space key) the state advances to the next state (depending on the tristate mode either between Tui::Unchecked and Tui::Checked or cycling through the states Tui::Unchecked, Tui::Checked and Tui::PartiallyChecked) and emits a stateChanged() signal.

Palette

Palette Color	Usage
control.fg, control.bg	Body of the checkbox (active, unfocused)
control.focused.fg, control.focused.bg	Body of the checkbox (active, focused)
control.disabled.fg, control.disabled.bg	Body of the checkbox (disabled)
control.shortcut.fg, control.shortcut.bg	Shortcut character in checkbox text.

ZCheckBox

class Tui::ZCheckBox : public Tui::ZWidget

A checkbox widget.

Constructors

ZCheckBox(const QString &text, Tui::ZWidget *parent = nullptr);

ZCheckBox(WithMarkupTag, const QString &markup, Tui::ZWidget *parent = nullptr);

Create the checkbox with the given text or markup.

Functions

QString text() const;

void setText(const QString &text);

Get or set the plain text content of the checkbox.

When set the shortcut is also reset.

When the content of the checkbox was most recently set using setMarkup() the returned text is empty.

QString markup() const;

void setMarkup(const QString &markup);

Get or set the text content of the checkbox using markup.

When set the shortcut is also reset, if the markup contains a mnemonic it is setup as new shortcut.

When the content of the checkbox was most recently set using setText() the returned markup is empty.

Tui::CheckState checkState() const;

void setCheckState(Tui::CheckState state);

The checkState is the displayed state of the checkbox. It can be Tui::Unchecked, Tui::Checked or Tui::PartiallyChecked.

Using the setter will not cause Tui::ZCheckBox::stateChanged() to be emitted.

bool isTristate() const;

void setTristate(bool tristate = true);

If the tristate attribute is false the checkbox alternates between the states Tui::Unchecked and Tui::Checked.

If tristate is enabled it cycles through the states Tui::Unchecked, Tui::Checked and Tui::PartiallyChecked.

void setShortcut(const Tui::ZKeySequence &key);

Set the given key as shortcut for the checkbox.

Signals

void stateChanged(Tui::CheckState state);

This signal is emitted when the user changes the state or the state is changed through the void Tui::ZCheckBox::toggle() function.

The new state is passed in the state parameter.

Slots

void toggle()

Toggle through the states of the checkbox and emit Tui::ZCheckBox::stateChanged().

void click()

If the checkbox is enabled, focus the checkbox and toggle through its states and emit Tui::ZCheckBox::stateChanged().

If the checkbox is disabled, does nothing.