qtquick-app-tutorial.qdoc 11.3 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 79
        \li Select \uicontrol Item in the navigator, and enter \e page in the
            \uicontrol Id field.

80
        \li In \uicontrol Library > \uicontrol Resources, select qt-logo.png and
81
            drag and drop it to the \e page in the navigator.
82 83 84 85 86

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

        \list a

87
            \li In the \uicontrol Id field, enter \e icon.
88

89 90
            \li In the \uicontrol Position field, set \uicontrol X to \e 10 and
                \uicontrol Y to \e 20.
91 92 93

        \endlist

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

98 99
        \li Drag and drop a \uicontrol Rectangle to \e page in the navigator and
            edit its properties.
100 101 102 103 104

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

        \list a

105
            \li In the \uicontrol Id field, enter \e topLeftRect.
106

107 108
            \li In the \uicontrol Size field, set \uicontrol W to \e 55 and
                \uicontrol H to \e 41, for the rectangle size to match the image
109
                size.
110

111
            \li In the \uicontrol Color field, click the
112
                \inlineimage button_color_none_normal.png
113 114
                (\uicontrol Transparent) button to make the rectangle
                transparent.
115

116
            \li In the \uicontrol {Border color} field, set the border color to
117
                \e #808080.
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
        \li Click \uicontrol {Layout}, and then click the
134
            \inlineimage anchor-fill-normal.png
135 136
            (\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
        \li In the \uicontrol Navigator, select the
173
            \inlineimage export_unchecked.png
174 175 176
            (\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 191
    \image qmldesigner-tutorial-ui-ready.png "Transitions UI"

192
    \section1 Adding Application Logic
193

194 195 196 197 198
    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).
199

200 201 202 203
    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.
204

205
    \list 1
206

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

210 211
            \quotefromfile transitions/main.qml
            \skipto ApplicationWindow
212
            \printuntil title
213

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

217
            \printuntil page
218

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

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

243
            \printuntil ]
244

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

    \endlist

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

    \section1 Adding Animation to the View

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

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

265
            \printuntil },
266

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

        \list a

272
            \li Click \uicontrol NumberAnimation in the code editor to display the
273
                \inlineimage refactormarker.png
274 275 276 277
                icon, and then click the icon to open the toolbar:

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

278
            \li In the \uicontrol Easing field, select \uicontrol Bounce.
279

280
            \li In the \uicontrol Subtype field, select \uicontrol Out.
281 282 283

        \endlist

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

288 289
            \dots
            \printuntil },
290

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

295 296
            \dots
            \printuntil ]
297

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

    \endlist

    Click the rectangles to view the animated transitions.
*/