Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qtquickcontrols-buttons.qdoc
Go to the documentation of this file.
1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \page qtquickcontrols-buttons.html
6 \title Button Controls
7 \ingroup qtquickcontrols-guidelines
8 \brief Guidelines for button controls
9
10 Qt Quick Controls offers a selection of button-like controls.
11
12 \annotatedlist qtquickcontrols-buttons
13
14 Each type of button has its own specific use case. The following
15 sections offer guidelines for choosing the appropriate type of button,
16 depending on the use case.
17
18 \section1 Button Control
19
20 \l Button is a clickable control that starts an action, or opens or
21 closes a popup. A button usually has a text label but it can also
22 contain an icon.
23
24 Button is a very suitable control when a popup or dialog needs
25 to perform an action. The most common examples are Apply, Cancel,
26 Save, Close and Help.
27
28 \image qtquickcontrols-button.gif
29 {Button demonstrating hover and press interactions}
30
31 Recommendations:
32
33 \list
34 \li The button's text should be a verb describing the action, or a noun matching
35 the title of the popup that will be opened.
36 \li Don't use a button to set state. \l Switch is more suitable for that.
37 \li Use the default font unless you have UI guidelines specifying otherwise.
38 \li If the text is localized, consider the influence of a longer text on the layout.
39 \endlist
40
41 \b {See also} \l Button and \l AbstractButton
42
43 \section1 CheckBox Control
44
45 \image qtquickcontrols-checkbox.gif
46 {Check boxes in a multi-selection list with some options selected}
47
48 \l CheckBox is used to build multi-selection option lists. Any number of
49 options can be selected, including none, but the options should
50 not be mutually exclusive.
51
52 Use a single CheckBox for a yes/no choice, such as when you have
53 to accept the terms of service agreement in a form.
54
55 For a single yes/no choice, it is also possible to use a switch. If the choice
56 concerns an option, it is best to use a CheckBox. If it concerns action to
57 be taken, a switch is recommended.
58
59 When options can be grouped, you can use a partially checked CheckBox to
60 represent the whole group. Use the checkbox's
61 \l {CheckBox::checkState}{partially checked state} when a user selects
62 some, but not all, sub-items in the group.
63
64 The three availables check states are: checked, partially checked and
65 unchecked.
66
67 The checkable options are often listed vertically.
68
69 Recommendations:
70 \list
71 \li The checkbox label should be a statement that the check mark makes true,
72 and that the absence of a check mark makes false.
73 \li The checkbox label should not contain a negative statement.
74 \li Use the default font, unless you have UI guidelines specifying otherwise.
75 \li If the text is localized, consider the influence of a longer text on the layout.
76 \endlist
77
78 \b {See also} \l CheckBox
79
80 \section1 DelayButton Control
81
82 \l DelayButton is a button that incorporates a delay before triggering an action.
83 This delay prevents accidental presses.
84
85 \image qtquickcontrols-delaybutton.gif
86 {Delay button with progress indicator showing timed delay}
87
88 Recommendations:
89 \list
90 \li Use in touch user interfaces.
91 \li Use for actions that must be triggered with care.
92 \endlist
93
94 \b {See also} \l Button and \l AbstractButton
95
96 \section1 RadioButton Control
97
98 \image qtquickcontrols-radiobutton.gif
99 {Radio buttons labeled First, Second, Third with First selected}
100
101 \l RadioButton is used to select only one option from a set of options.
102 Selecting one option automatically deselects the one selected before.
103
104 If there are only two mutually exclusive options, combine them into a
105 single checkbox or a switch.
106
107 Recommendations:
108
109 \list
110 \li Limit the label text to one line.
111 \li Ensure that a sensible default option is checked.
112 \li List RadioButton options vertically.
113 \li If the text is localized, consider the influence of a longer text on the layout.
114 \li Use the default font, unless you have UI guidelines that specify otherwise.
115 \li Just like with CheckBox, do not make the list too large.
116 \li In order to avoid confusion, do not put two groups of radio buttons next to each
117 other.
118 \endlist
119
120 \b {See also} \l RadioButton
121
122 \section1 RoundButton Control
123
124 \l RoundButton is a clickable control that starts an action, or opens or
125 closes a popup. A round button with a square image icon or one-letter font
126 icon is circular. A circular RoundButton takes less space than a normal
127 \l Button, and can also be used as a floating action button.
128
129 \image qtquickcontrols-roundbutton.png
130 {Round button with checkmark icon}
131
132 Recommendations:
133
134 \list
135 \li Keep labels short and concise.
136 \li If the text is localized, consider the influence of a longer text on the layout.
137 \endlist
138
139 \b {See also} \l RoundButton
140
141 \section1 Switch Control
142
143 \image qtquickcontrols-switch.png
144 {Switch control labeled Switch in off state}
145
146 \l Switch represents a physical switch that allows users to choose between an "on"
147 or "off" state.
148 Use a switch for binary operations that take effect immediately after it has been
149 switched on. For example, a switch to turn WIFI on or off.
150
151 Recommendations:
152
153 \list
154 \li Keep labels short and concise.
155 \li If the text is localized, consider the influence of a longer text on the layout.
156 \endlist
157
158 \b {See also} \l Switch
159
160 \section1 ToolButton Control
161
162 \image qtquickcontrols-toolbutton.png
163 {Tool button labeled ToolButton}
164
165 \l ToolButton is nearly identical to \l Button, but it has a graphical
166 appearance that makes it more suitable for insertion into a \l ToolBar.
167
168 \b {See also} \l ToolButton
169
170 \section1 Related Information
171 \list
172 \li \l {Qt Quick Controls Guidelines}
173 \endlist
174*/