qtquick-app-tutorial.qdoc 11.2 KB
Newer Older
1 2
/****************************************************************************
**
3 4
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
5
**
6
** This file is part of the Qt Creator documentation.
7
**
8 9 10 11 12 13 14
** 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.
15
**
16
** GNU Free Documentation License Usage
17 18
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
19 20 21 22
** 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.
23 24 25 26 27 28 29 30 31 32
**
****************************************************************************/

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

/*!
33
    \contentspage {Qt Creator Manual}
Oswald Buddenhagen's avatar
Oswald Buddenhagen committed
34
    \previouspage creator-tutorials.html
35
    \example transitions
36
    \nextpage creator-writing-program.html
37

38
    \title Creating a Qt Quick Application
39

40
    This tutorial uses built-in QML types and illustrates basic concepts of
41
    \l{Qt Quick}.
42

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

    \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
52 53 54
    For tutorials that describe using Qt Quick Controls, see
    \l{Qt Quick Text Editor Guide} and \l{Qt Quick Controls - UI Forms}.

55
    \include creator-tutorial-create-qq-project.qdocinc
56 57 58 59 60 61

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

62 63 64 65
    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.
66

67
    \list 1
68

69 70
        \li In the \uicontrol Projects view, double-click the MainForm.ui.qml
            file to open it in \QMLD.
71

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

74
        \li In the \uicontrol Navigator, select \uicontrol RowLayout and press
75
            \key Delete to delete it.
76

77 78
        \li In \uicontrol Library > \uicontrol Resources, select qt-logo.png and
            drag and drop it to the \uicontrol Item in the navigator.
79 80 81 82 83

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

        \list a

84
            \li In the \uicontrol Id field, enter \e icon.
85

86 87
            \li In the \uicontrol Position field, set \uicontrol X to \e 10 and
                \uicontrol Y to \e 20.
88 89 90

        \endlist

91
        \li Right-click the resource file, qml.qrc, in the \uicontrol Projects
92 93
            view, and select \uicontrol {Add Existing File} to add qt-logo.png
            to the resource file for deployment.
94

95 96
        \li Drag and drop a \uicontrol Rectangle to \e page in the navigator and
            edit its properties.
97 98 99 100 101

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

        \list a

102
            \li In the \uicontrol Id field, enter \e topLeftRect.
103

104 105 106
            \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.
107

108
            \li In the \uicontrol Color field, click the
109
                \inlineimage qmldesigner-transparent-button.png
110 111
                (\uicontrol Transparent) button to make the rectangle
                transparent.
112

113
            \li In the \uicontrol {Border color} field, set the border color to
114
                \e #808080.
115

116 117
            \li In the \uicontrol Radius field, select \e 6 to create rounded
                corners for the rectangle.
118

119 120 121
            \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.
122 123 124

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

125 126
            \li In the \uicontrol Margin field, select \e 20 for the top anchor
                and \e 10 for the left anchor.
127 128 129

        \endlist

130
        \li Drag and drop a \uicontrol {Mouse Area} type from the
131
            \uicontrol Library to \e topLeftRect in the navigator.
132

133 134 135 136
        \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.
137

138
        \li In the \uicontrol Navigator, copy topLeftRect (by pressing
139 140 141
            \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.
142

143
        \li  Select topLeftRect1 and edit its properties:
144 145 146

        \list a

147
            \li In the \uicontrol Id field, enter \e middleRightRect.
148

149
            \li In \uicontrol {Layout}, select the vertical center anchor button and
150 151 152
                then the right anchor button to
                anchor the rectangle to the middle right margin of the screen.

153 154
            \li In the \uicontrol Margin field, select \e 10 for the right
                anchor and \e 0 for the vertical center anchor.
155 156 157

        \endlist

158
        \li Select topLeftRect2 and edit its properties:
159 160 161

        \list a

162
            \li In the \uicontrol Id field, enter \e bottomLeftRect.
163

164
            \li In \uicontrol {Layout}, select the bottom and left anchor buttons to
165 166
                anchor the rectangle to the bottom left margin of the screen.

167 168
            \li In the \uicontrol Margin field, select \e 20 for the bottom
                anchor and \e 10 for the left anchor.
169

170
        \endlist
171

172 173 174 175 176
        \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.
177

178
        \li Press \key {Ctrl+S} to save the changes.
179

180
    \endlist
181

182 183 184
    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.
185

186 187 188
    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.
189

190
    \section1 Adding Application Logic
191

192 193 194 195 196
    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).
197

198 199 200 201
    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.
202

203
    \list 1
204

205 206
        \li Specify the window size and background color as properties of
            the ApplicationWindow type:
207

208 209 210
            \quotefromfile transitions/main.qml
            \skipto ApplicationWindow
            \printuntil height
211

212 213
        \li Specify an id for the MainForm type to be able to use the properties
            that you exported in \e MainForm.ui.qml:
214

215
            \printuntil page
216

217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233
        \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 }
234

235
        \li Bind the position of the Qt logo to the
236 237 238 239 240
            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:

241
            \printuntil ]
242

243
        \li Press \key {Ctrl+R} to run the application.
244 245 246 247 248 249 250

    \endlist

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

    \section1 Adding Animation to the View

251 252
    Add transitions inside the state group to define how the properties change
    when the Qt logo moves
253 254 255 256 257 258
    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

259
        \li In the code editor, add the following code to specify that when
260 261 262
            moving to State1, the x and y coordinates of the Qt logo change
            linearly over a duration of 1 second:

263
            \printuntil },
264

265
        \li You can use the Qt Quick toolbar for animation to change the easing
266 267 268 269
            curve type from linear to OutBounce:

        \list a

270
            \li Click \uicontrol NumberAnimation in the code editor to display the
271 272 273 274 275
                \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"

276
            \li In the \uicontrol Easing field, select \uicontrol Bounce.
277

278
            \li In the \uicontrol Subtype field, select \uicontrol Out.
279 280 281

        \endlist

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

286 287
            \dots
            \printuntil },
288

289
        \li Add the following code to specify that for any other state changes,
290 291 292
            the x and y coordinates of the Qt logo change linearly over a
            duration of 200 milliseconds:

293 294
            \dots
            \printuntil ]
295

296
        \li Press \key {Ctrl+R} to run the application.
297 298 299 300 301

    \endlist

    Click the rectangles to view the animated transitions.
*/