qtquick-app-tutorial.qdoc 10.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
    \example transitions
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
    This tutorial describes how to use \QC to implement Qt Quick states and
37 38
    transitions. We create an application that displays a Qt logo that moves
    between three rectangles on the page when you click them.
39 40 41 42 43 44

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

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

Leena Miettinen's avatar
Leena Miettinen committed
45 46 47
    For tutorials that describe using Qt Quick Controls, see
    \l{Qt Quick Text Editor Guide} and \l{Qt Quick Controls - UI Forms}.

48
    \include creator-tutorial-create-qq-project.qdocinc
49 50 51 52 53 54

    \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.

55 56 57 58
    To use the \e qt-logo.png image in your application, you must copy it from
    the Qt examples directory to the project directory (same subdirectory as
    the QML file). The image appears in \uicontrol Resources. You can also use
    any other image or a QML type, instead.
59

60
    \list 1
61

62 63
        \li In the \uicontrol Projects view, double-click the MainForm.ui.qml
            file to open it in \QMLD.
64

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

67
        \li In the \uicontrol Navigator, select \uicontrol RowLayout and press
68
            \key Delete to delete it.
69

70 71
        \li In \uicontrol Library > \uicontrol Resources, select qt-logo.png and
            drag and drop it to the \uicontrol Item in the navigator.
72 73 74 75 76

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

        \list a

77
            \li In the \uicontrol Id field, enter \e icon.
78

79 80
            \li In the \uicontrol Position field, set \uicontrol X to \e 10 and
                \uicontrol Y to \e 20.
81 82 83

        \endlist

84
        \li Right-click the resource file, qml.qrc, in the \uicontrol Projects
85 86
            view, and select \uicontrol {Add Existing File} to add qt-logo.png
            to the resource file for deployment.
87

88 89
        \li Drag and drop a \uicontrol Rectangle to \e page in the navigator and
            edit its properties.
90 91 92 93 94

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

        \list a

95
            \li In the \uicontrol Id field, enter \e topLeftRect.
96

97 98 99
            \li In the \uicontrol Size field, set \uicontrol W to \e 46 and
                \uicontrol H to \e 55, for the rectangle size to match the image
                size.
100

101
            \li In the \uicontrol Color field, click the
102
                \inlineimage qmldesigner-transparent-button.png
103 104
                (\uicontrol Transparent) button to make the rectangle
                transparent.
105

106
            \li In the \uicontrol {Border color} field, set the border color to
107
                \e #808080.
108

109 110
            \li In the \uicontrol Radius field, select \e 6 to create rounded
                corners for the rectangle.
111

112 113 114
            \li Click \uicontrol {Layout}, and then click the top and left
                anchor buttons to anchor the rectangle to the top left corner of
                the page.
115 116 117

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

118 119
            \li In the \uicontrol Margin field, select \e 20 for the top anchor
                and \e 10 for the left anchor.
120 121 122

        \endlist

123
        \li Drag and drop a \uicontrol {Mouse Area} type from the
124
            \uicontrol Library to \e topLeftRect in the navigator.
125

126 127 128 129
        \li Click \uicontrol {Layout}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            (\uicontrol {Fill to Parent}) button to anchor the mouse area to the
            rectangle.
130

131
        \li In the \uicontrol Navigator, copy topLeftRect (by pressing
132 133 134
            \key {Ctrl+C}) and paste it to the \e page in the navigator twice
            (by pressing \key {Ctrl+V}). \QC renames the new instances of the
            type topLeftRect1 and topLeftRect2.
135

136
        \li  Select topLeftRect1 and edit its properties:
137 138 139

        \list a

140
            \li In the \uicontrol Id field, enter \e middleRightRect.
141

142
            \li In \uicontrol {Layout}, select the vertical center anchor button and
143 144 145
                then the right anchor button to
                anchor the rectangle to the middle right margin of the screen.

146 147
            \li In the \uicontrol Margin field, select \e 10 for the right
                anchor and \e 0 for the vertical center anchor.
148 149 150

        \endlist

151
        \li Select topLeftRect2 and edit its properties:
152 153 154

        \list a

155
            \li In the \uicontrol Id field, enter \e bottomLeftRect.
156

157
            \li In \uicontrol {Layout}, select the bottom and left anchor buttons to
158 159
                anchor the rectangle to the bottom left margin of the screen.

160 161
            \li In the \uicontrol Margin field, select \e 20 for the bottom
                anchor and \e 10 for the left anchor.
162

163
        \endlist
164

165 166 167 168 169
        \li In the \uicontrol Navigator, select the
            \inlineimage qmldesigner-export-item-button.png
            (\uicontrol Export) button for each type to export all types as
            properties. This enables you to use the properties in the
            \e main.qml file.
170

171
        \li Press \key {Ctrl+S} to save the changes.
172

173
    \endlist
174

175 176 177
    To check your code, you can open MainForm.ui.qml in the
    \uicontrol Edit mode and compare it with the \l{transitions/MainForm.ui.qml}
    {MainForm.ui.qml} example file.
178

179 180 181
    The UI is now ready and you can switch to editing the \e main.qml file in
    the \uicontrol Edit mode to add animation to the application, as described
    in the following section.
182

183
    \section1 Adding Application Logic
184

185 186 187 188 189
    The new project wizard adds boilerplate code to the \e main.qml file to
    create menu items and push buttons. Modify the boilerplate code by removing
    obsolete code and by adding new code. You removed the push buttons from the
    UI form, so you also need to remove the corresponding code from
    \e main.qml (or the application cannot be built).
190

191 192 193 194
    Edit the main.qml file to add pointers to two additional states: \e State1
    and \e 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.
195

196
    \list 1
197

198 199
        \li Specify the window size and background color as properties of
            the ApplicationWindow type:
200

201 202 203
            \quotefromfile transitions/main.qml
            \skipto ApplicationWindow
            \printuntil height
204

205 206
        \li Specify an id for the MainForm type to be able to use the properties
            that you exported in \e MainForm.ui.qml:
207

208
            \printuntil page
209

210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226
        \li Add a pointer to the clicked expressions in \uicontrol mouseArea1:

            \printuntil }

            The expression sets the state to the base state and returns the
            image to its initial position.

        \li Add a pointer to a clicked expression to \uicontrol mouseArea2
            to set the state to \e State1:

            \printuntil }

        \li Add a pointer to a clicked expression to \uicontrol mouseArea3 to
            set the state to \e State2:

            \printuntil }
            \printuntil }
227

228
        \li Bind the position of the Qt logo to the
229 230 231 232 233
            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:

234
            \printuntil ]
235

236
        \li Press \key {Ctrl+R} to run the application.
237 238 239 240 241 242 243

    \endlist

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

    \section1 Adding Animation to the View

244 245
    Add transitions inside the state group to define how the properties change
    when the Qt logo moves
246 247 248 249 250 251
    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

252
        \li In the code editor, add the following code to specify that when
253 254 255
            moving to State1, the x and y coordinates of the Qt logo change
            linearly over a duration of 1 second:

256
            \printuntil },
257

258
        \li You can use the Qt Quick toolbar for animation to change the easing
259 260 261 262
            curve type from linear to OutBounce:

        \list a

263
            \li Click \uicontrol NumberAnimation in the code editor to display the
264 265 266 267 268
                \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"

269
            \li In the \uicontrol Easing field, select \uicontrol Bounce.
270

271
            \li In the \uicontrol Subtype field, select \uicontrol Out.
272 273 274

        \endlist

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

279 280
            \dots
            \printuntil },
281

282
        \li Add the following code to specify that for any other state changes,
283 284 285
            the x and y coordinates of the Qt logo change linearly over a
            duration of 200 milliseconds:

286 287
            \dots
            \printuntil ]
288

289
        \li Press \key {Ctrl+R} to run the application.
290 291 292 293 294

    \endlist

    Click the rectangles to view the animated transitions.
*/