qtquick-app-tutorial.qdoc 13 KB
Newer Older
1 2
/****************************************************************************
**
3
** Copyright (c) 2014 Digia Plc and/or its subsidiary(-ies).
hjk's avatar
hjk committed
4
** Contact: http://www.qt-project.org/legal
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 \gui{File > New File or Project > Application >
51
            Qt Quick Application > Choose}.
52

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

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

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

62
        \li Select \l{glossary-buildandrun-kit}{kits} for running and building your project,
63
            and then click \gui{Next}.
64

65 66
            \note Kits are listed if they have been specified in \gui Tools >
            \gui Options > \gui {Build & Run} > \gui Kits.
67

68
        \li Select \gui Next in the following dialogs to use the default
69 70
            settings.

71
        \li Review the project settings, and click \gui{Finish} (on Windows and
72
            Linux) or \gui Done (on OS X) to create the project.
73

74
        \li Press \key {Ctrl+R} (or \key {Cmd+R}) to run the application.
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90

    \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:
91 92
    \c {C:\Qt\Qt5.3.0\5.3.0\msvc2010\examples\declarative\animation\states}. The
    image appears
93
    in the \gui Resources pane. You can also use any other image or a QML
94
    type, instead.
95 96 97

    \list 1

98
        \li In the \gui Projects view, double-click the main.qml file
99 100
            to open it in the code editor.

101
        \li Click \gui Design to open the file in \QMLD.
102 103 104

            \image qmldesigner-tutorial-desing-mode.png "Transitions project in Design Mode"

105
        \li In the \gui Navigator pane, select \gui Text and press \key Delete to
106 107
            delete it.

108
        \li Select \gui Window to edit its properties.
109 110 111 112 113

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

        \list a

114
            \li In the \gui Id field, enter \e page, to be able to reference the
115 116 117
                window from other places.

            \li In the code editor, set the window background color to #343434:
118

119 120 121
            \quotefromfile transitions/main.qml
            \skipto Window {
            \printuntil color
122

123
            \li Delete the \c {Qt.quit();} command.
124 125 126

        \endlist

127
        \li In the \gui Library view, \gui Resources tab, select states.png and
128 129 130 131 132 133
            drag and drop it to the canvas.

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

        \list a

134
            \li In the \gui Id field, enter \e icon.
135

136
            \li In the \gui Position field, set \gui X to 10 and \gui Y to 20.
137 138 139

        \endlist

140 141 142 143 144 145 146
        \li Double-click the resource file, qml.qrc, in the \gui Projects view
            to add states.png to the resource file for deployment.

        \li Click \gui Add and select states.png.

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

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

        \list a

153
            \li In the \gui Id field, enter \e topLeftRect.
154

155
            \li In the \gui Size field, set \gui W and \gui H to 64, for the
156 157
                rectangle size to match the image size.

158
            \li In the \gui Color field, click the
159
                \inlineimage qmldesigner-transparent-button.png
160
                (\gui Transparent) button to make the rectangle transparent.
161

162
            \li In the \gui Border field, set the border color to #808080.
163

164
            \li In the \gui Rectangle group, \gui Border field, set the border
165 166 167 168 169 170
                width to 1.

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

173
            \li In the \gui Radius field, select 6 to create rounded corners for
174 175
                the rectangle.

176
            \li Click \gui {Layout}, and then click the top and left anchor
177 178 179 180 181
                buttons to anchor the rectangle to the top left corner of the
                page.

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

182
            \li In the \gui Margin field, select 20 for the top anchor and 10
183 184 185 186
                for the left anchor.

        \endlist

187
        \li In the \gui Navigator pane, drag and drop the \gui {Mouse Area}
188
            from \e page to \e topLeftRect to make it apply only to the
189 190
            rectangle and not to the whole page.

191
        \li  Edit the \gui {Mouse Area} properties:
192 193 194

        \list a

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

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

204 205 206
                \quotefromfile transitions/main.qml
                \skipto MouseArea
                \printuntil }
207 208 209

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

        \endlist

214 215
            The qml.main file should now look as follows:

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

223
        \li In the \gui Navigator pane, 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 \gui Id field, enter \e middleRightRect.
233

234
            \li In \gui {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 \gui 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 \gui Id field, enter \e bottomLeftRect.
256

257
            \li In \gui {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 \gui 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 275 276 277 278
            \quotefromfile transitions/main.qml
            \skipto Window {
            \printuntil State2
            \printuntil }
            \printuntil }
            \printuntil }
279

280 281
        \endlist

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

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

    \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:
298 299 300
    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:
301 302 303

    \list 1

304
        \li Bind the position of the Qt logo to the
305 306 307 308 309
            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:

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

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

    \endlist

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

    \section1 Adding Animation to the View

322 323
    Add transitions inside the state group to define how the properties change
    when the Qt logo moves
324 325 326 327 328 329
    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

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

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

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

        \list a

343
            \li Click \gui NumberAnimation in the code editor to display the
344 345 346 347 348
                \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"

349
            \li In the \gui Easing field, select \gui Bounce.
350

351
            \li In the \gui Subtype field, select \gui Out.
352 353 354

        \endlist

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

359 360
            \dots
            \printuntil },
361

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

366 367
            \dots
            \printuntil ]
368

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

    \endlist

    Click the rectangles to view the animated transitions.

375 376 377 378
    \section1 Example Code

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

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

383
*/