Differential D13922 Diff 37244 source/components/checkbox.rst

Changeset View

Standalone View

View Options

source/components/checkbox.rst

1Check box 1​Checkbox
2========= 2​========
3 3​
4Purpose 4​Purpose
5------- 5​-------
6 6​
7A *check box* is a control that permits the user to make multiple 7​A *checkbox* is a control that permits the user to make multiple
8selections from a number of options. Check boxes are used to toggle an 8​selections from a number of options. Checkboxes are used to toggle an
9option on or off, or to select or deselect an item. Users make a 9​option on or off, or to select or deselect an item. Users make a
10decision between two clearly opposite choices, e.g. 'on vs. off', 'apply 10​decision between two clearly opposite choices, e.g. 'on vs. off', 'apply
11vs. don't apply', 'show vs. hide'. 11​vs. don't apply', 'show vs. hide'.
12 12​
13Example 13​Example
14------- 14​-------
15 15​
16Guidelines 16​Guidelines
17---------- 17​----------
18 18​
19Is this the right control 19​Is this the right control
20~~~~~~~~~~~~~~~~~~~~~~~~~ 20​~~~~~~~~~~~~~~~~~~~~~~~~~
21 21​
22- Use check boxes for non-exclusive options that have clear 22​- Use checkboxes for non-exclusive options that have clear
23 alternatives. Mutually exclusive options should use a set of 23​ alternatives. Mutually exclusive options should use a set of
24 :doc:`radio buttons <radiobutton>` or a :doc:`combo box <combobox>`. 24​ :doc:`radio buttons <radiobutton>` or a :doc:`combo box <combobox>`.
25 25​
26.. container:: flex 26​.. container:: flex
27 27​
28 .. container:: 28​ .. container::
29 29​
30 .. figure:: /img/Ambiguous_Opposite_Bad.qml.png 30​ .. figure:: /img/Ambiguous_Opposite_Bad.qml.png
31 :figclass: border 31​ :figclass: border
32 32​
33 :iconred:`BAD` |br| 33​ :iconred:`BAD` |br|
34 Do not use a check box if the opposite is ambiguous. 34​ Do not use a checkbox if the opposite is ambiguous.
35 35​
36 .. container:: 36​ .. container::
37 37​
38 .. figure:: /img/Ambiguous_Opposite_Good.qml.png 38​ .. figure:: /img/Ambiguous_Opposite_Good.qml.png
39 :figclass: border 39​ :figclass: border
40 40​
41 :noblefir:`GOOD` |br| 41​ :noblefir:`GOOD` |br|
42 Using two radio buttons removes the need to guess. 42​ Using two radio buttons removes the need to guess.
Show All 19 Lines61 .. figure:: /img/No_Command_2_Good.qml.png
62 :figclass: border 62​ :figclass: border
63 63​
64 :noblefir:`GOOD` |br| 64​ :noblefir:`GOOD` |br|
65 Consider using a :doc:`push button <pushbutton>` instead. 65​ Consider using a :doc:`push button <pushbutton>` instead.
66 66​
67Behavior 67​Behavior
68~~~~~~~~ 68​~~~~~~~~
69 69​
70- Checking a check box should always "enable" an option or change the 70​- Checking a checkbox should always "enable" an option or change the
71 state of an option to "on". Checking a negative or disabling option 71​ state of an option to "on". Checking a negative or disabling option
72 is a double negative and causes confusion and errors. 72​ is a double negative and causes confusion and errors.
73 73​
74.. container:: flex 74​.. container:: flex
75 75​
76 .. container:: 76​ .. container::
77 77​
78 .. figure:: /img/Checkbox_Enable_Bad.qml.png 78​ .. figure:: /img/Checkbox_Enable_Bad.qml.png
Show All 12 Lines90- Use the mixed state only to indicate that an option is set for some,
91 but not all, child objects. Mixed state must not be used to represent 91​ but not all, child objects. Mixed state must not be used to represent
92 a third state. 92​ a third state.
93 93​
94.. image:: /img/Checkbox_Mixed_State.qml.png 94​.. image:: /img/Checkbox_Mixed_State.qml.png
95 :alt: Example for mixed state. 95​ :alt: Example for mixed state.
96 96​
97 97​
98- Users must not be able to set a mixed state directly. 98​- Users must not be able to set a mixed state directly.
99- Clicking a mixed state check box enables all child objects. 99​- Clicking a mixed state checkbox enables all child objects.
100- Do not use sliding switches in Desktop applications. They only offer 100​- Do not use sliding switches in Desktop applications. They only offer
101 good user interaction on touch screens, so they should only be used 101​ good user interaction on touch screens, so they should only be used
102 in applications for mobile devices. 102​ in applications for mobile devices.
103 103​
104.. container:: flex 104​.. container:: flex
105 105​
106 .. container:: 106​ .. container::
107 107​
108 .. figure:: /img/Checkbox_Switch_Desktop.qml.png 108​ .. figure:: /img/Checkbox_Switch_Desktop.qml.png
109 109​
110 :iconred:`BAD` 110​ :iconred:`BAD`
111 111​
112 .. container:: 112​ .. container::
113 113​
114 .. figure:: /img/Checkbox_Switch_Mobile.qml.png 114​ .. figure:: /img/Checkbox_Switch_Mobile.qml.png
115 115​
116 :noblefir:`GOOD` 116​ :noblefir:`GOOD`
117 117​
118Appearance 118​Appearance
119~~~~~~~~~~ 119​~~~~~~~~~~
120 120​
121If you are using qt widgets you should use one of Qt's Layout Classes 121​If you are using qt widgets you should use one of Qt's Layout Classes
122like , that will take care of lay outing and spacing of your controls. 122​like , that will take care of lay outing and spacing of your controls.
123 123​
124- The text of a check box is on the right of its tick rectangle, which 124​- The text of a checkbox is on the right of its tick rectangle, which
125 can make it difficult to avoid blank areas on the left side of the 125​ can make it difficult to avoid blank areas on the left side of the
126 form. To keep the layout of the form balanced you can use one of the 126​ form. To keep the layout of the form balanced you can use one of the
127 following approaches: 127​ following approaches:
128 128​
129 - Group check boxes together in the widget column and add a label 129​ - Group checkboxes together in the widget column and add a label
130 describing the group in the label column. 130​ describing the group in the label column.
131 131​
132 .. image:: /img/Grouped_checkboxes.qml.png 132​ .. image:: /img/Grouped_checkboxes.qml.png
133 :alt: Grouped checkboxes 133​ :alt: Grouped checkboxes
134 134​
135 135​
136 - Make the check boxes span the two columns, but keep them at the 136​ - Make the checkboxes span the two columns, but keep them at the
137 bottom of the form. Remark: This interferes with other layout 137​ bottom of the form. Remark: This interferes with other layout
138 guidelines 138​ guidelines
139 139​
140 .. image:: /img/Two_column_checkboxes.qml.png 140​ .. image:: /img/Two_column_checkboxes.qml.png
141 :alt: Checkboxes spanning two columns 141​ :alt: Checkboxes spanning two columns
142 142​
143 - If all else fails, add a label describing the checkbox on the left 143​ - If all else fails, add a label describing the checkbox on the left
144 side of the checkbox, then set the text of the checkbox to 144​ side of the checkbox, then set the text of the checkbox to
145 "Enabled", "On", or similar. 145​ "Enabled", "On", or similar.
146 146​
147 .. image:: /img/Checkbox_separate_label.qml.png 147​ .. image:: /img/Checkbox_separate_label.qml.png
148 :alt: Using a separate title label for the checkbox. 148​ :alt: Using a separate title label for the checkbox.
149 149​
150- When options are subordinate to a check box (e.g. Audio level can 150​- When options are subordinate to a checkbox (e.g. Audio level can
151 only be set if the Activate Audio option is selected), this relation 151​ only be set if the Activate Audio option is selected), this relation
152 should be visualized by indenting the sub-options. There are two 152​ should be visualized by indenting the sub-options. There are two
153 options to do so: 153​ options to do so:
154 154​
155 - When you are using a left-aligned check box, indent the 155​ - When you are using a left-aligned checkbox, indent the
156 sub-options by using a horizontal spacer of SizeType "Minimum". 156​ sub-options by using a horizontal spacer of SizeType "Minimum".
157 157​
158 .. image:: /img/Suboption_spacer.qml.png 158​ .. image:: /img/Suboption_spacer.qml.png
159 :alt: Aligning sub-options with a horizontal spacer of SizeType "Minimum". 159​ :alt: Aligning sub-options with a horizontal spacer of SizeType "Minimum".
160 160​
161 - When you are using a check box that is placed right to its label, 161​ - When you are using a checkbox that is placed right to its label,
162 indent the sub-options in the same vertical axis as the check box. 162​ indent the sub-options in the same vertical axis as the checkbox.
163 163​
164 .. image:: /img/Suboption_right.qml.png 164​ .. image:: /img/Suboption_right.qml.png
165 :alt: Aligning sub-options with the same vertical axis as the 165​ :alt: Aligning sub-options with the same vertical axis as the
166 checkbox itself.| 166​ checkbox itself.|
167 167​
168- If activating a choice affects the appearance or the enabled state of 168​- If activating a choice affects the appearance or the enabled state of
169 other controls, place them next to the check box (group). 169​ other controls, place them next to the checkbox (group).
170- Align check boxes vertically rather than horizontally, as this makes 170​- Align checkboxes vertically rather than horizontally, as this makes
171 them easier to scan visually. Use horizontal or rectangular 171​ them easier to scan visually. Use horizontal or rectangular
172 alignments only if they greatly improve the layout of the window. 172​ alignments only if they greatly improve the layout of the window.
173- If certain controls in a configuration dialog are only relevant if a 173​- If certain controls in a configuration dialog are only relevant if a
174 certain check box is checked (i.e. they are dependent controls), 174​ certain checkbox is checked (i.e. they are dependent controls),
175 disable them instead of hiding them if that check box is unchecked. 175​ disable them instead of hiding them if that checkbox is unchecked.
176 176​
177- Do not separate check box and label. Clicking on both the box and the 177​- Do not separate checkbox and label. Clicking on both the box and the
178 label should toggle the option. 178​ label should toggle the option.
179 179​
180 .. image:: /img/HIG_Checkbox5.png 180​ .. image:: /img/HIG_Checkbox5.png
181 :alt: Separate check box and label 181​ :alt: Separate checkbox and label
182 182​
183- Do not add line breaks. If necessary place an additional label below 183​- Do not add line breaks. If necessary place an additional label below
184 the check box. 184​ the checkbox.
185 185​
186.. container:: flex 186​.. container:: flex
187 187​
188 .. container:: 188​ .. container::
189 189​
190 .. figure:: /img/Checkbox_Alignment_Bad.qml.png 190​ .. figure:: /img/Checkbox_Alignment_Bad.qml.png
191 191​
192 :iconred:`BAD` 192​ :iconred:`BAD`
193 193​
194 .. container:: 194​ .. container::
195 195​
196 .. figure:: /img/Checkbox_Alignment_Good.qml.png 196​ .. figure:: /img/Checkbox_Alignment_Good.qml.png
197 197​
198 :noblefir:`GOOD` 198​ :noblefir:`GOOD`
199 199​
200- Label a group of check box with a descriptive caption to the top left 200​- Label a group of checkbox with a descriptive caption to the top left
201 of the group (cf. :doc:`alignment </layout/alignment>`). 201​ of the group (cf. :doc:`alignment </layout/alignment>`).
202- Create a buddy relation so access keys are assigned. 202​- Create a buddy relation so access keys are assigned.
203- Use :doc:`sentence style capitalization </style/writing/capitalization>` for check box items. 203​- Use :doc:`sentence style capitalization </style/writing/capitalization>`
204​ for checkbox items.
204- Do not use ending punctuation (neither dot nor colon) for group 205​- Do not use ending punctuation (neither dot nor colon) for group
205 label. 206​ label.