1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page qtquickcontrols-buttons.html
7 \ingroup qtquickcontrols-guidelines
8 \brief Guidelines for button controls
10 Qt Quick Controls offers a selection of button-like controls.
12 \annotatedlist qtquickcontrols-buttons
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.
18 \section1 Button Control
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
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,
28 \image qtquickcontrols-button.gif
33 \li The button's text should be a verb describing the action, or a noun matching
34 the title of the popup that will be opened.
35 \li Don't use a button to set state. \l Switch is more suitable for that.
36 \li Use the default font unless you have UI guidelines specifying otherwise.
37 \li If the text is localized, consider the influence of a longer text on the layout.
40 \b {See also} \l Button and \l AbstractButton
42 \section1 CheckBox Control
44 \image qtquickcontrols-checkbox.gif
46 \l CheckBox is used to build multi-selection option lists. Any number of
47 options can be selected, including none, but the options should
48 not be mutually exclusive.
50 Use a single CheckBox for a yes/no choice, such as when you have
51 to accept the terms of service agreement in a form.
53 For a single yes/no choice, it is also possible to use a switch. If the choice
54 concerns an option, it is best to use a CheckBox. If it concerns action to
55 be taken, a switch is recommended.
57 When options can be grouped, you can use a partially checked CheckBox to
58 represent the whole group. Use the checkbox's
59 \l {CheckBox::checkState}{partially checked state} when a user selects
60 some, but not all, sub-items in the group.
62 The three availables check states are: checked, partially checked and
65 The checkable options are often listed vertically.
69 \li The checkbox label should be a statement that the check mark makes true,
70 and that the absence of a check mark makes false.
71 \li The checkbox label should not contain a negative statement.
72 \li Use the default font, unless you have UI guidelines specifying otherwise.
73 \li If the text is localized, consider the influence of a longer text on the layout.
76 \b {See also} \l CheckBox
78 \section1 DelayButton Control
80 \l DelayButton is a button that incorporates a delay before triggering an action.
81 This delay prevents accidental presses.
83 \image qtquickcontrols-delaybutton.gif
87 \li Use in touch user interfaces.
88 \li Use for actions that must be triggered with care.
91 \b {See also} \l Button and \l AbstractButton
93 \section1 RadioButton Control
95 \image qtquickcontrols-radiobutton.gif
97 \l RadioButton is used to select only one option from a set of options.
98 Selecting one option automatically deselects the one selected before.
100 If there are only two mutually exclusive options, combine them into a
101 single checkbox or a switch.
106 \li Limit the label text to one line.
107 \li Ensure that a sensible default option is checked.
108 \li List RadioButton options vertically.
109 \li If the text is localized, consider the influence of a longer text on the layout.
110 \li Use the default font, unless you have UI guidelines that specify otherwise.
111 \li Just like with CheckBox, do not make the list too large.
112 \li In order to avoid confusion, do not put two groups of radio buttons next to each
116 \b {See also} \l RadioButton
118 \section1 RoundButton Control
120 \l RoundButton is a clickable control that starts an action, or opens or
121 closes a popup. A round button with a square image icon or one-letter font
122 icon is circular. A circular RoundButton takes less space than a normal
123 \l Button, and can also be used as a floating action button.
125 \image qtquickcontrols-roundbutton.png
130 \li Keep labels short and concise.
131 \li If the text is localized, consider the influence of a longer text on the layout.
134 \b {See also} \l RoundButton
136 \section1 Switch Control
138 \image qtquickcontrols-switch.png
140 \l Switch represents a physical switch that allows users to choose between an "on"
142 Use a switch for binary operations that take effect immediately after it has been
143 switched on. For example, a switch to turn WIFI on or off.
148 \li Keep labels short and concise.
149 \li If the text is localized, consider the influence of a longer text on the layout.
152 \b {See also} \l Switch
154 \section1 ToolButton Control
156 \image qtquickcontrols-toolbutton.png
158 \l ToolButton is nearly identical to \l Button, but it has a graphical
159 appearance that makes it more suitable for insertion into a \l ToolBar.
161 \b {See also} \l ToolButton
163 \section1 Related Information
165 \li \l {Qt Quick Controls Guidelines}