qtquick-app-tutorial.qdoc 13.6 KB
Newer Older
1 2
/****************************************************************************
**
Eike Ziller's avatar
Eike Ziller committed
3 4
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing
5
**
hjk's avatar
hjk committed
6
** This file is part of Qt Creator
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
**
**
** GNU Free Documentation License
**
** 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.
**
**
****************************************************************************/

// **********************************************************************
// 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.
// **********************************************************************

/*!
26
    \contentspage {Qt Creator Manual}
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
27
    \previouspage creator-tutorials.html
28
    \page creator-qml-application.html
29
    \nextpage creator-writing-program.html
30

31
    \title Creating a Qt Quick Application
32

33
    This tutorial uses built-in QML types and illustrates basic concepts of
34
    \l{Qt Quick}.
35

36 37
    This tutorial describes how to use \QC to implement Qt Quick states and
    transitions. We
38 39
    create an application that displays a Qt logo that moves between three rectangles on the
    page when you click them.
40 41 42 43 44 45 46 47 48 49

    \image qmldesigner-tutorial.png "States and transitions example"

    For more information about using \QMLD, see
    \l{Developing Qt Quick Applications}.

    \section1 Creating the Project

    \list 1

50
        \li Select \uicontrol{File > New File or Project > Application >
51
            Qt Quick Application > Choose}.
52

53
        \li In the \uicontrol{Name} field, type \b {Transitions}.
54

55 56 57
        \li In the \uicontrol {Create in} field, enter the path for the project files.
            For example, \c {C:\Qt\examples}, and then click \uicontrol{Next} (on
            Windows and Linux) or \uicontrol Continue (on OS X).
58

59 60
        \li In the \uicontrol {Qt Quick component set} field, select
            \uicontrol {Qt Quick 2.1}.
61

62 63 64 65 66 67
            \note This selection determines the set of files that the wizard
            generates and their contents. The instructions in this tutorial
            might not apply if you select some other component set, such as Qt
            Quick 2.4. The wizard indicates which Qt version each component set
            requires at minimum.

68
        \li Select \l{glossary-buildandrun-kit}{kits} for running and building your project,
69
            and then click \uicontrol{Next}.
70

71 72 73 74
            \note Kits are listed if they have been specified in \uicontrol Tools >
            \uicontrol Options > \uicontrol {Build & Run} > \uicontrol Kits (on Windows and Linux)
            or in \uicontrol {Qt Creator} > \uicontrol Preferences \uicontrol {Build & Run} >
            \uicontrol Kits (on OS X).
75

76
        \li Select \uicontrol Next in the following dialogs to use the default
77 78
            settings.

79 80
        \li Review the project settings, and click \uicontrol{Finish} (on Windows and
            Linux) or \uicontrol Done (on OS X) to create the project.
81

82
        \li Press \key {Ctrl+R} (or \key {Cmd+R}) to run the application.
83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98

    \endlist

    \QC generates a default QML file that you can modify to create the main view
    of the application.

    \image qmldesigner-tutorial-project.png "Transitions project in Edit mode"

    \section1 Creating the Main View

    The main view of the application displays a Qt logo in the top left corner
    of the screen and two empty rectangles.

    To use the states.png image in your application, you must copy it to the
    project directory (same subdirectory as the QML file) from the examples
    directory in the Qt installation directory. For example:
99
    \c {C:\Qt\Examples\Qt-5.4\declarative\animation\states}. The image appears
100
    in \uicontrol Resources. You can also use any other image or a QML
101
    type, instead.
102 103 104

    \list 1

105
        \li In the \uicontrol Projects view, double-click the main.qml file
106 107
            to open it in the code editor.

108
        \li Click \uicontrol Design to open the file in \QMLD.
109

Mitch Curtis's avatar
Mitch Curtis committed
110
            \image qmldesigner-tutorial-design-mode.png "Transitions project in Design Mode"
111

112 113
        \li In the \uicontrol Navigator, select \uicontrol MouseArea and
            \uicontrol Text and press \key Delete to delete them.
114

115
        \li Select \uicontrol Window to edit its properties.
116 117 118 119 120

            \image qmldesigner-tutorial-page.png "Page properties"

        \list a

121
            \li In the \uicontrol Id field, enter \e page, to be able to reference the
122 123
                window from other places.

124 125
            \li In the \uicontrol Color field, set the window background color
                to #343434.
126 127 128

        \endlist

129
        \li In \uicontrol Library > \uicontrol Resources, select states.png and
130 131 132 133 134 135
            drag and drop it to the canvas.

            \image qmldesigner-tutorial-user-icon.png "Image properties"

        \list a

136
            \li In the \uicontrol Id field, enter \e icon.
137

138
            \li In the \uicontrol Position field, set \uicontrol X to 10 and \uicontrol Y to 20.
139 140 141

        \endlist

142 143 144
        \li Right-click the resource file, qml.qrc, in the \uicontrol Projects
            view, and select \uicontrol {Open in Editor} to add states.png to
            the resource file for deployment.
145

146
        \li Click \uicontrol Add and select states.png.
147

148 149
        \li In the \uicontrol Design mode, \uicontrol Library view, \uicontrol {QML Types} tab,
            select \uicontrol Rectangle,
150 151 152 153 154 155
            drag and drop it to the canvas, and edit its properties.

            \image qmldesigner-tutorial-topleftrect.png "Rectangle properties"

        \list a

156
            \li In the \uicontrol Id field, enter \e topLeftRect.
157

158
            \li In the \uicontrol Size field, set \uicontrol W and \uicontrol H to 64, for the
159 160
                rectangle size to match the image size.

161
            \li In the \uicontrol Color field, click the
162
                \inlineimage qmldesigner-transparent-button.png
163
                (\uicontrol Transparent) button to make the rectangle transparent.
164

165
            \li In the \uicontrol Border field, set the border color to #808080.
166

167
            \li In the \uicontrol Rectangle group, \uicontrol Border field, set the border
168 169
                width to 1.

170
                \note If the \uicontrol Border field does not appear after you set the
171 172 173
                border color, try setting the border color to solid by clicking
                the
                \inlineimage qmldesigner-solid-color-button.png
174
                (\uicontrol {Solid Color}) button.
175

176
            \li In the \uicontrol Radius field, select 6 to create rounded corners for
177 178
                the rectangle.

179
            \li Click \uicontrol {Layout}, and then click the top and left anchor
180 181 182 183 184
                buttons to anchor the rectangle to the top left corner of the
                page.

                \image qmldesigner-tutorial-topleftrect-layout.png "Layout tab"

185
            \li In the \uicontrol Margin field, select 20 for the top anchor and 10
186 187 188 189
                for the left anchor.

        \endlist

190 191
        \li Drag and drop a \uicontrol {Mouse Area} type from the
            \uicontrol Library to \e topLeftRect in the \uicontrol Navigator.
192

193
        \li  Edit the \uicontrol {Mouse Area} properties:
194 195 196

        \list a

197
            \li Click \uicontrol {Layout}, and then click the
198
                \inlineimage qmldesigner-anchor-fill-screen.png
199
                (\uicontrol {Fill to Parent}) button to anchor the mouse area to the
200
                rectangle.
201

202
            \li In the code editor, edit the pointer to the clicked expression
203
                in the mouse area, as illustrated by the following code
204 205
                snippet:

206 207 208
                \quotefromfile transitions/main.qml
                \skipto MouseArea
                \printuntil }
209 210 211

                The expression sets the state to the base state and returns the
                image to its initial position.
212
                You will create stateGroup later.
213 214 215

        \endlist

216 217
            The qml.main file should now look as follows:

218 219
            \quotefromfile transitions/main.qml
            \skipto Window {
220
            \printuntil mouseArea1
221
            \printuntil }
222

223
        \li In the \uicontrol Navigator, copy topLeftRect (by pressing
224
            \key {Ctrl+C}) and paste it to the canvas twice (by pressing
225
            \key {Ctrl+V}). \QC renames the new instances of the type
226 227
            topLeftRect1 and topLeftRect2.

228
        \li  Select topLeftRect1 and edit its properties:
229 230 231

        \list a

232
            \li In the \uicontrol Id field, enter \e middleRightRect.
233

234
            \li In \uicontrol {Layout}, select the vertical center anchor button and
235 236 237
                then the right anchor button to
                anchor the rectangle to the middle right margin of the screen.

238
            \li In the \uicontrol Margin field, select 10 for the right anchor and 0
239 240
                for the vertical center anchor.

241
            \li In the code editor, add a pointer to a clicked expression to the
242
                mouse area. The following expression sets the state to
243 244
                \e State1:

245
                \c {onClicked: stateGroup.state = 'State1'}
246 247 248 249 250

                You will create State1 later.

        \endlist

251
        \li Select topLeftRect2 and edit its properties:
252 253 254

        \list a

255
            \li In the \uicontrol Id field, enter \e bottomLeftRect.
256

257
            \li In \uicontrol {Layout}, select the bottom and left anchor buttons to
258 259
                anchor the rectangle to the bottom left margin of the screen.

260
            \li In the \uicontrol Margin field, select 20 for the bottom anchor and 10
261 262
                for the left anchor.

263
            \li In the code editor, add a pointer to a clicked expression to the
264
                mouse area. The following expression sets the state to
265 266
                \e State2:

267
                \c {onClicked: stateGroup.state = 'State2'}
268 269 270

                You will create State2 later.

271 272
            The qml.main file should now look as follows:

273 274
            \quotefromfile transitions/main.qml
            \skipto Window {
275
            \printuntil mouseArea3
276 277
            \printuntil }
            \printuntil }
278

279 280
        \endlist

281
        \li Press \key {Ctrl+S} to save the changes.
282

283
        \li Press \key {Ctrl+R} to run the application.
284 285 286 287 288 289 290 291 292 293 294 295 296

    \endlist

    \image qmldesigner-tutorial.png "States and transitions example"

    You should see the Qt logo in the top left rectangle, and two additional
    rectangles in the center right and bottom left of the screen.

    You can now create additional states to add views to the application.

    \section1 Adding Views

    In the .qml file, you already created pointers to two additional states:
297 298 299
    State1 and State2. You cannot use the \QMLD to add states for a Window QML
    type. Use the code editor to add the states inside a StateGroup QML type and
    refer to them by using the id of the state group:
300 301 302

    \list 1

303
        \li Bind the position of the Qt logo to the
304 305 306 307 308
            rectangle to make sure that the logo is displayed within the
            rectangle when the view is scaled on different sizes of screens. Set
            expressions for the x and y properties, as illustrated by the
            following code snippet:

309 310 311
            \quotefromfile transitions/main.qml
            \skipto StateGroup {
            \printuntil ]
312

313
        \li Press \key {Ctrl+R} to run the application.
314 315 316 317 318 319 320

    \endlist

    Click the rectangles to move the Qt logo from one rectangle to another.

    \section1 Adding Animation to the View

321 322
    Add transitions inside the state group to define how the properties change
    when the Qt logo moves
323 324 325 326 327 328
    between states. The transitions apply animations to the Qt logo. For example,
    the Qt logo bounces back when it moves to the middleRightRect and eases into
    bottomLeftRect. Add the transitions in the code editor.

    \list 1

329
        \li In the code editor, add the following code to specify that when
330 331 332
            moving to State1, the x and y coordinates of the Qt logo change
            linearly over a duration of 1 second:

333 334 335
            \dots
            \skipto transitions
            \printuntil },
336

337
        \li You can use the Qt Quick toolbar for animation to change the easing
338 339 340 341
            curve type from linear to OutBounce:

        \list a

342
            \li Click \uicontrol NumberAnimation in the code editor to display the
343 344 345 346 347
                \inlineimage qml-toolbar-indicator.png
                icon, and then click the icon to open the toolbar:

                \image qmldesigner-tutorial-quick-toolbar.png "Qt Quick toolbar for animation"

348
            \li In the \uicontrol Easing field, select \uicontrol Bounce.
349

350
            \li In the \uicontrol Subtype field, select \uicontrol Out.
351 352 353

        \endlist

354
        \li Add the following code to specify that when moving to State2, the x
355 356 357
            and y coordinates of the Qt logo change over a duration of 2
            seconds, and an InOutQuad easing function is used:

358 359
            \dots
            \printuntil },
360

361
        \li Add the following code to specify that for any other state changes,
362 363 364
            the x and y coordinates of the Qt logo change linearly over a
            duration of 200 milliseconds:

365 366
            \dots
            \printuntil ]
367

368
        \li Press \key {Ctrl+R} to run the application.
369 370 371 372 373

    \endlist

    Click the rectangles to view the animated transitions.

374 375 376 377
    \section1 Example Code

    When you have completed the steps, the main.qml file should look as follows:

378 379 380
            \quotefromfile transitions/main.qml
            \skipto Window {
            \printuntil /^\}/
381

382
*/