aboutsummaryrefslogtreecommitdiffstats
path: root/src/imports/controls/doc/src/qtquickcontrols2-buttons.qdoc
blob: 434cf839200668c796fc8596c2e1ecaeb5e05cf6 (plain)
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
/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qtquickcontrols2-buttons.html
    \title Button Controls
    \ingroup qtquickcontrols2-guidelines
    \brief Guidelines for button controls

    Qt Quick Controls 2 offers a selection of button-like controls.

    \annotatedlist qtquickcontrols2-buttons

    Each type of button has its own specific use case. The following
    sections offer guidelines for choosing the appropriate type of button,
    depending on the use case.

    \section1 Button Control

    \l Button is a clickable control that starts an action, or opens or
    closes a popup. A button usually has a text label but it can also
    contain an icon.

    Button is a very suitable control when a popup or dialog needs
    to perform an action. The most common examples are Apply, Cancel,
    Save, Close and Help.

    \image qtquickcontrols2-button.gif

    Recommendations:

    \list
    \li The button's text should be a verb describing the action, or a noun matching
        the title of the popup that will be opened.
    \li Don't use a button to set state. \l Switch is more suitable for that.
    \li Use the default font unless you have UI guidelines specifying otherwise.
    \li If the text is localized, consider the influence of a longer text on the layout.
    \endlist

    \b {See also} \l Button and \l AbstractButton

    \section1 CheckBox Control

    \image qtquickcontrols2-checkbox.gif

    \l CheckBox is used to build multi-selection option lists. Any number of
    options can be selected, including none, but the options should
    not be mutually exclusive.

    Use a single CheckBox for a yes/no choice, such as when you have
    to accept the terms of service agreement in a form.

    For a single yes/no choice, it is also possible to use a switch. If the choice
    concerns an option, it is best to use a CheckBox. If it concerns action to
    be taken, a switch is recommended.

    When options can be grouped, you can use a partially checked CheckBox to
    represent the whole group. Use the checkbox's indeterminate state when
    a user selects some, but not all, sub-items in the group.

    The three availables statuses are: checked, unchecked and disabled.
    "Disabled" is useful when the user should not be able to check or uncheck
    a checkbox.

    The checkable options are often listed vertically.

    Recommendations:
    \list
    \li The checkbox label should be a statement that the check mark makes true,
    and that the absence of a check mark makes false.
    \li The checkbox label should not contain a negative statement.
    \li Use the default font, unless you have UI guidelines specifying otherwise.
    \li If the text is localized, consider the influence of a longer text on the layout.
    \endlist

    \b {See also} \l CheckBox

    \section1 RadioButton Control

    \image qtquickcontrols2-radiobutton.gif

    \l RadioButton is used to select only one option from a set of options.
    Selecting one option automatically deselects the one selected before.

    The set of options should not be too large, otherwise it starts taking too much
    space on the screen. In that case it would be more practical to use a \l ComboBox.

    If there are only two mutually exclusive options, combine them into a
    single checkbox or a switch.

    Recommendations:

    \list
    \li Limit the label text to one line.
    \li Ensure that a sensible default option is checked.
    \li List RadioButton options vertically.
    \li If the text is localized, consider the influence of a longer text on the layout.
    \li Use the default font, unless you have UI guidelines that specify otherwise.
    \li Just like with CheckBox, do not make the list too large.
    \li In order to avoid confusion, do not put two groups of radio buttons next to each
        other.
    \endlist

    \b {See also} \l RadioButton

    \section1 RoundButton Control

    \l RoundButton is a clickable control that starts an action, or opens or
    closes a popup. A round button with a square image icon or one-letter font
    icon is circular. A circular RoundButton takes less space than a normal
    \l Button, and can also be used as a floating action button.

    \image qtquickcontrols2-roundbutton.png

    Recommendations:

    \list
    \li Keep labels short and concise.
    \li If the text is localized, consider the influence of a longer text on the layout.
    \endlist

    \b {See also} \l RoundButton

    \section1 Switch Control

    \image qtquickcontrols2-switch.png

    \l Switch represents a physical switch that allows users to choose between an "on"
    or "off" state.
    Use a switch for binary operations that take effect immediately after it has been
    switched on. For example, a switch to turn WIFI on or off.

    Recommendations:

    \list
    \li Keep labels short and concise.
    \li If the text is localized, consider the influence of a longer text on the layout.
    \endlist

    \b {See also} \l Switch

    \section1 ToolButton Control

    \image qtquickcontrols2-toolbutton.png

    \l ToolButton is nearly identical to \l Button, but it has a graphical
    appearance that makes it more suitable for insertion into a \l ToolBar.

    \b {See also} \l ToolButton

    \section1 Related Information
    \list
    \li \l {Qt Quick Controls 2 Guidelines}
    \endlist
*/