1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
.. _ZCheckBox:
ZCheckBox
=========
.. rst-class:: tw-flex-imgs
* .. figure:: tpi/checkbox.tpi
Checkbox with text "CheckBox"
* .. figure:: tpi/checkbox-focus.tpi
in focused state
* .. figure:: tpi/checkbox-disabled.tpi
in disabled state
A checkbox allows users to select or deselect an option.
In contrast to :ref:`radiobuttons <ZRadioButton>` each checkbox has an independent state.
The state can be toggled by using :kbd:`Space` or if set by using a keyboard mnemonic.
The key to toggle the checkbox is usually shown highlighted when set using :ref:`markup <ControlMarkup>` 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.
.. rst-class:: tw-flex-imgs
* .. figure:: tpi/checkbox-checked.tpi
checked state
* .. figure:: tpi/checkbox-partially-checked.tpi
partially checked state
Example
-------
.. literalinclude:: examples/widgets/checkbox.cpp
:start-after: // snippet-start
:end-before: // snippet-end
:dedent:
Keyboard Usage
--------------
.. list-table::
:class: noborder
:widths: 33 67
:align: left
:header-rows: 1
* - Key
- Result
* - :kbd:`Space`
- Activate the button
* - :kbd:`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 :kbd:`Space` key) the state advances to the next state
(depending on the tristate mode either between :cpp:enumerator:`Tui::Unchecked` and :cpp:enumerator:`Tui::Checked` or
cycling through the states :cpp:enumerator:`Tui::Unchecked`, :cpp:enumerator:`Tui::Checked` and :cpp:enumerator:`Tui::PartiallyChecked`)
and emits a :cpp:func:`~Tui::ZCheckBox::stateChanged` signal.
Palette
-------
.. list-table::
:class: noborder
:align: left
:header-rows: 1
* - Palette Color
- Usage
* - ``control.fg``, ``control.bg``
- Body of the |control| (active, **unfocused**)
* - ``control.focused.fg``, ``control.focused.bg``
- Body of the |control| (active, **focused**)
* - ``control.disabled.fg``, ``control.disabled.bg``
- Body of the |control| (**disabled**)
* - ``control.shortcut.fg``, ``control.shortcut.bg``
- Shortcut character in |control| text.
ZCheckBox
---------
.. cpp:class:: Tui::ZCheckBox : public Tui::ZWidget
A checkbox widget.
**Constructors**
.. cpp:function:: ZCheckBox(const QString &text, Tui::ZWidget *parent=nullptr);
.. cpp:function:: ZCheckBox(WithMarkupTag, const QString &markup, Tui::ZWidget *parent=nullptr);
Create the |control| with the given ``text`` or ``markup``.
**Functions**
.. cpp:function:: QString text() const;
.. cpp:function:: void setText(const QString &text);
Get or set the plain text content of the |control|.
When set the shortcut is also reset.
When the content of the |control| was most recently set using :cpp:func:`setMarkup` the returned text is empty.
.. cpp:function:: QString markup() const;
.. cpp:function:: void setMarkup(const QString &markup);
Get or set the text content of the |control| 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 |control| was most recently set using :cpp:func:`setText` the returned markup is empty.
.. cpp:function:: Tui::CheckState checkState() const;
.. cpp:function:: void setCheckState(Tui::CheckState state);
The ``checkState`` is the displayed state of the checkbox.
It can be :cpp:enumerator:`Tui::Unchecked`, :cpp:enumerator:`Tui::Checked` or :cpp:enumerator:`Tui::PartiallyChecked`.
Using the setter will not cause :cpp:func:`Tui::ZCheckBox::stateChanged` to be emitted.
.. cpp:function:: bool isTristate() const;
.. cpp:function:: void setTristate(bool tristate = true);
If the tristate attribute is :cpp:expr:`false` the checkbox alternates between the states :cpp:enumerator:`Tui::Unchecked` and
:cpp:enumerator:`Tui::Checked`.
If tristate is enabled it cycles through the states :cpp:enumerator:`Tui::Unchecked`,
:cpp:enumerator:`Tui::Checked` and :cpp:enumerator:`Tui::PartiallyChecked`.
.. cpp:function:: void setShortcut(const Tui::ZKeySequence &key);
Set the given ``key`` as shortcut for the |control|.
**Signals**
.. cpp:function:: void stateChanged(Tui::CheckState state);
This signal is emitted when the user changes the state or the state is changed through the
:cpp:func:`void Tui::ZCheckBox::toggle()` function.
The new state is passed in the ``state`` parameter.
**Slots**
.. cpp:function:: void toggle()
Toggle through the states of the checkbox and emit :cpp:func:`Tui::ZCheckBox::stateChanged`.
.. cpp:function:: void click()
If the checkbox is enabled, focus the checkbox and toggle through its states
and emit :cpp:func:`Tui::ZCheckBox::stateChanged`.
If the checkbox is disabled, does nothing.
.. |control| replace:: checkbox
|
