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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
|
/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** 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 https://www.qt.io/terms-conditions. For further
** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
**
****************************************************************************/
// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************
/*!
\page quick-buttons.html
\previouspage quick-components-creating.html
\nextpage quick-scalable-image.html
\title Creating Buttons
To create a button component:
\list 1
\li Select \uicontrol File > \uicontrol {New File or Project} >
\if defined(qtcreator)
\uicontrol Qt > \uicontrol {Qt Quick UI File} >
\else
\uicontrol {Qt Quick Files} > \uicontrol {Qt Quick UI File} >
\endif
\uicontrol Choose to create a \l{UI Files}{UI file} called
Button.ui.qml (for example).
\note Components are listed in \l Library > \uicontrol Components >
\uicontrol {My Components} only if the filename begins with a
capital letter.
\li Click \uicontrol {Design} to edit the file in \l {Form Editor}.
\li In \l Navigator, select \uicontrol Item and set the width
(\uicontrol W) and height (\uicontrol H) of the button in
\l Properties.
\li Drag-and-drop a \uicontrol Rectangle from \l Library >
\uicontrol Components > \uicontrol {Default Components} >
\uicontrol Basic to the component in \uicontrol Navigator. This
creates a nested component where the Item is the parent of the
Rectangle. Components are positioned relative to their parents.
\li In the \uicontrol Properties view, modify the appearance of the
rectangle:
\list a
\li In the \uicontrol Color field, select the button color.
\li In the \uicontrol Radius field, set the radius of
the rectangle to produce rounded corners for the button.
\li Select \uicontrol {Layout}, and then select the
\inlineimage icons/anchor-fill.png
(\uicontrol {Fill to Parent}) button to anchor the Rectangle to
the Item.
\endlist
\li Drag-and-drop a \uicontrol {Text} component to the Item in
\uicontrol Navigator.
\li In the \uicontrol Properties view, edit the properties of the
\uicontrol Text component
\list a
\li In the \uicontrol Text field, enter \e Button.
You can select the text color in the \uicontrol {Text color} field and the
font, size, and style in the
\uicontrol Font section.
\li In the \uicontrol Alignment field, select the center buttons to align
the text to the center of the button.
\li Select \uicontrol Layout > \uicontrol {Fill to Parent}
to anchor the text to the whole button area.
\endlist
\li Press \key {Ctrl+S} to save the button.
\image qmldesigner-button.png "Button component"
\endlist
To be useful, the button component has to be created in a project.
When you work on other files in the project to create screens
or other components for the UI, the button component appears in
\uicontrol Library > \uicontrol Components > \uicontrol {My Components}.
You can use it to create button instances and modify their properties
to assign them useful IDs, change their appearance, and set the button
text for each button instance, for example.
To create a graphical button that scales beautifully without using
vector graphics, use the \l {Border Image} component. For more
information, see \l{Creating Scalable Buttons and Borders}.
*/
/*!
\previouspage quick-buttons.html
\page quick-scalable-image.html
\if defined(qtdesignstudio)
\nextpage qtquick-properties.html
\else
\nextpage studio-optimized-3d-scenes.html
\endif
\title Creating Scalable Buttons and Borders
You can use the \l {Border Image} component to display an image, such as a
PNG file, as a border and a background.
Use two border images and suitable graphics to change the appearance of
a button when it is clicked. You can use use \l{Adding States}{states}
to determine which image is visible depending on whether the mouse
button is pressed down. You could add more images and states to
change the appearance of the button depending on other mouse events,
such as hovered.
Use a \l Text component to add button text.
You can use states also to change the button text color and font size. For
example, you can scale the button text up or down.
Add a \l {Mouse Area} component that covers the whole area and
reacts to mouse events.
\image qmldesigner-borderimage-type.png "Button component in Form Editor and States"
\section1 Creating the Button Component
To create a button component, select \uicontrol File >
\uicontrol {New File or Project} >
\if defined(qtcreator)
\uicontrol Qt > \uicontrol {Qt Quick UI File} >
\else
\uicontrol {Qt Quick Files} > \uicontrol {Qt Quick UI File} >
\endif
\uicontrol Choose to create a \l{UI Files}{UI file} called Button.ui.qml
(for example).
\note Components are listed in \l Library > \uicontrol Components >
\uicontrol {My Components} only if the filename begins with a
capital letter.
\section1 Constructing the Button Component
To construct the button component:
\list 1
\li Click \uicontrol {Design} to edit the UI file in \l {Form Editor}.
\li Select \l Library > \uicontrol Assets > \inlineimage plus.png
to copy the image files you want to use to the project folder.
\li In \l Navigator, select the root component and set the
width (\uicontrol W) and height (\uicontrol H) of the button in the
\l Properties view to match the size of the images
you plan to use. This specifies the initial size of the button
component.
\li Drag-and-drop two \uicontrol {Border Image} components from
\uicontrol Library > \uicontrol Components >
\uicontrol {Default Components} > \uicontrol Basic to the root
component in \uicontrol Navigator.
\li Drag-and-drop a \uicontrol Text component to the root component.
\li Drag-and-drop a \uicontrol {Mouse Area} to the root component.
\li Select a border image to edit the values of its properties:
\list a
\li In the \uicontrol Id field, enter an ID for the border
image. In this example, we use the ID \e inactiveButton.
\li In the \uicontrol Source field, select the image file for
the border image. For example, inactive_button.png.
\li In the \uicontrol {Layout} tab, select the
\inlineimage icons/anchor-fill.png
(\uicontrol {Fill to Parent}) button to always make the
image the same size as its parent. This makes the button
component scalable, because the image size is bound to the
component size.
\endlist
\li Select the other border image to edit the values of its properties
similarly:
\list a
\li In the \uicontrol Id field, enter \e activeButton.
\li In the \uicontrol Source field, select the image file
for the button when it is clicked. For example,
active_button.png.
\li In the \uicontrol {Layout} tab, select the
\inlineimage icons/anchor-fill.png
(\uicontrol {Fill to Parent}) button.
\endlist
\li Select the text component to specify font size and color in
\uicontrol Properties:
\list a
\li In the \uicontrol Color field, use the \l{Picking Colors}
{color picker} to select the font color, or enter a value
in the field.
\li In \uicontrol Font group, \uicontrol Size field, enter the
font size.
\li In the \uicontrol {Layout} tab, select
\inlineimage icons/anchor-center-vertical.png
(\uicontrol {Vertical Center}) and
\inlineimage icons/anchor-center-horizontal.png
(\uicontrol {Horizontal Center}) buttons to inherit the
vertical and horizontal centering from the parent.
This ensures that the button label is centered when the
component is resized.
\endlist
\endlist
\section1 Using States to Change Component Property Values
\list 1
\li In the \l States view, select \uicontrol {Create New State}
twice to create two new states.
\image qmldesigner-borderimage-states.png "Active and inactive states"
\li Select \uicontrol State1.
\li Change the state name to \e active.
\li Select \inlineimage icons/action-icon.png
, and then select \uicontrol {Set when Condition} to determine
when the state should be applied.
\li In the \uicontrol {Binding Editor}, select the \c mouseArea
component and the \c pressed signal to specify that the state is
applied when the mouse button is pressed down.
\image qmldesigner-borderimage-bindings.png "Active state when condition"
\li Select the text component in \uicontrol Navigator to specify that the
text size is scaled up when the button is pressed down.
\li In \uicontrol Properties, select the \uicontrol Advanced section, and
increase the value of the \uicontrol Scale property.
\li Select \e inactiveButton in \uicontrol Navigator to hide
it in the \e active state by changing the value of its
\uicontrol Visibility property in \uicontrol Properties.
\li Select \uicontrol State2.
\li Change the state name to \e inactive.
\li Set the when condition for the state to \c !mouseArea.pressed to
specify that the state is applied when the mouse button is not
pressed down.
\image qmldesigner-borderimage-bindings1.png "Inactive state when condition"
\li Press \key {Ctrl+S} to save the button.
\li Select the \inlineimage live_preview.png
(\uicontrol {Show Live Preview}) button to check how the
button behaves when you click it. You can drag the preview
window borders to see what happens when you resize the
component.
\endlist
To be useful, the button component has to be created in a project.
When you work on other files in the project to create screens
or other components for the UI, the button component appears in
\l Library > \uicontrol Components > \uicontrol {My Components}.
You can drag-and-drop it to \uicontrol {Form Editor} or
\uicontrol Navigator to create button instances and modify the values
of their properties to assign them useful IDs, change their appearance,
and set the button text for each button instance, for example.
For more information about positioning buttons on screens, see
\l{Scalable Layouts}.
\image qmldesigner-borderimage.png "Button preview as part of a screen"
*/
|
