qtquick-screens.qdoc 15.9 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 26
**
**
** 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.
// **********************************************************************

/*!

27
    \contentspage {Qt Creator Manual}
28 29
    \previouspage quick-scalable-image.html
    \page quick-screens.html
30
    \nextpage qtquick-iso-icon-browser.html
31 32 33

    \title Creating Screens

34
    You can use predefined QML types and your own components to create
35 36 37
    screens. Typically, the main qml file in a Qt Quick project specifies the
    main window of an application.

38 39
    The QML files in the project folder are displayed in \uicontrol {QML Components}
    in the \uicontrol Library.
40

41 42
    You can also use ready-made Qt Quick 1 Components (for Qt 4) to create
    screens with a native look and feel for a particular target platform.
43 44 45
    Since Qt 5.1, Qt Quick Controls, Dialogs, and Layouts are available for
    creating classic desktop-style user interfaces using Qt Quick 2.1. You can
    use the Qt Quick Controls Styles to customize Qt Quick Controls.
46 47 48 49 50

    \section1 Adding Components to Screens

    \list 1

51
        \li Drag and drop components from the \uicontrol Library to the editor.
52

53 54
        \li Select components in the \uicontrol Navigator to edit their
            properties in the \uicontrol Properties pane.
55 56 57 58 59 60 61 62 63

            For example, you can anchor components to a position on the screen.

    \endlist


    \section1 Using Data Models

    You can create the following types of views to organize items provided by
64
    \l{Models and Views in Qt Quick}{data models}:
65 66 67

    \list

68
        \li GridView provides a grid vizualization of a model.
69

70
        \li ListView provides a list vizualization of a model.
71

72
        \li PathView visualizes the contents of a model along a path.
73 74 75

    \endlist

76
    When you add a GridView, ListView, or PathView, the ListModel and the
77
    delegate component that creates an instance for each item in the model are
78
    added automatically. You can edit item properties
79
    in the \uicontrol Properties pane or
80 81 82 83 84
    in the code editor. You can also replace the default model and
    delegate with other, more complex models and delegates in the code editor.

    \section1 Positioning Items on Screens

85 86
    The position of an item on the canvas can be either absolute or relative
    to other items. If you are designing a static user interface,
87
    \l{Important Concepts In Qt Quick - Positioning#manual-positioning}
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
    {manual positioning} provides the most efficient form of positioning items
    on the screen. For a dynamic user interface, you can employ the following
    positioning methods provided by Qt Quick:

    \list

        \li \l{Setting Bindings}

        \li \l{Setting Anchors and Margins}

        \li \l{Using Positioners}

        \li \l{Using Layouts}

        \li \l{Using Split Views}

    \endlist

    \section2 Setting Bindings

108
    \l{Positioning with Bindings}
109
    {Property binding} is a declarative way of specifying the value of a property.
110
    Binding allows a property value to be expressed as a JavaScript expression
111 112 113 114 115 116 117
    that defines the value relative to other property values or data accessible
    in the application. The property value is automatically kept up to date if
    the other properties or data values change.

    Property bindings are created implicitly in QML whenever a property is
    assigned a JavaScript expression. To set JavaScript expressions as values of
    properties in \QMLD, click the circle icon next to a property to open a
118
    context menu, and select \uicontrol {Set Binding}.
119 120 121

    \image qmldesigner-set-expression.png "Type properties context menu"

122
    To remove bindings, select \uicontrol Reset in the context menu.
123 124

    For more information on the JavaScript environment provided by QML, see
125
    \l{Integrating QML and JavaScript}.
126 127 128 129 130 131 132 133

    \QMLD cannot show bindings and using them might have a negative impact on
    performance, so consider setting anchors and margins for items, instead.
    For example, instead of setting \c {parent.width} for an item, you could
    anchor the item to its sibling items on the left and the right.

    \section2 Setting Anchors and Margins

134
    In an \l{Important Concepts In Qt Quick - Positioning#anchors}
135 136 137 138
    {anchor-based} layout, each QML type can be thought of as having a set of
    invisible \e anchor lines: top, bottom, left, right, fill, horizontal
    center, vertical center, and baseline.

139
    In the \uicontrol Layout pane you can set anchors and margins for items. To set
140 141 142 143 144 145 146 147 148 149 150 151
    the anchors of an item, click the anchor buttons. You can combine the
    top/bottom, left/right, and horizontal/vertical anchors to anchor items in
    the corners of the parent item or center them horizontally or vertically
    within the parent item.

    \image qmldesigner-anchor-buttons.png "Anchor buttons"

    Specifying the baseline anchor in \QMLD is not supported. You can specify it
    using the code editor.

    For performance reasons, you can only anchor an item to its siblings and
    direct parent. By default, an item is anchored to its parent when you
152
    use the anchor buttons. Select a sibling of the item in the \uicontrol Target
153 154 155 156 157 158 159 160 161
    field to anchor to it, instead.

    Arbitrary anchoring is not supported. For example, you cannot specify:
    \c {anchor.left: parent.right}. You have to specify: \c {anchor.left: parent.left}.
    When you use the anchor buttons, anchors to the parent item are always
    specified to the same side. However, anchors to sibling items are specified
    to the opposite side: \c {anchor.left: sibling.right}. This allows you to keep
    sibling items together.

162
    In the following image, \uicontrol{Rectangle 2} is anchored to \uicontrol{Rectangle 1}
163 164 165 166
    on its left and to the bottom of its parent.

    \image qmldesigner-anchors.png "Anchoring sibling items"

167
    The anchors for \uicontrol{Rectangle 2} are specified as follows in code:
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185

    \qml
    Rectangle {
        id: rectangle2
        anchors.left: rectangle1.right
        anchors.leftMargin: 15
        anchors.bottom: parent.bottom
        anchors.bottomMargin: 15
        //
    }
    \endqml

    Margins specify the amount of empty space to leave to the outside of an item.
    Margins only have meaning for anchors. They do not take any effect when using
    other layouts or absolute positioning.

    \section2 Using Positioners

186
    \l{Important Concepts In Qt Quick - Positioning#positioners}
187 188 189 190 191 192
    {Positioner items} are container items that manage the positions of items in
    a declarative user interface. Positioners behave in a similar way to the
    layout managers used with standard Qt widgets, except that they are also
    containers in their own right.

    You can use the following positioners to arrange items on screens:
193 194 195

    \list

196
        \li \l{Column} arranges its child items vertically.
197

198
        \li \l{Row} arranges its child items horizontally.
199

200
        \li \l{Grid}
201 202 203
            arranges its child items so that they are aligned in a grid and
            are not overlapping.

204
        \li \l{Flow}
205 206 207 208
            arranges its child items side by side, wrapping as necessary.

    \endlist

209
    To lay out several items in a Column, Row, Grid, or Flow, select
210
    the items on the canvas, and then select \uicontrol Layout in the context
211 212
    menu.

213 214
    \section2 Using Layouts

215 216 217
    From Qt 5.1, you can use QML types in the \l{qtquicklayouts-index.html}
    {Qt Quick Layouts} module to arrange Qt Quick items on screens. Unlike
    positioners, they manage both the positions and sizes of items in a
218 219 220 221 222 223
    declarative interface. They are well suited for resizable user interfaces.

    You can use the following layout types to arrange items on screens:

    \list

224
        \li \l{Layout} provides attached properties for items pushed onto a
225
            \uicontrol {Column Layout}, \uicontrol {Row Layout}, or \uicontrol {Grid Layout}.
226

227
        \li ColumnLayout provides a grid layout with only one column.
228

229
        \li RowLayout provides a grid layout with only one row.
230

231
        \li GridLayout provides a way of dynamically arranging items in a
232 233 234 235
            grid.

    \endlist

236 237 238
    To lay out several items in a \uicontrol {Column Layout}, \uicontrol {Row Layout}, or
    \uicontrol {Grid Layout}, select the items on the canvas, and then select
    \uicontrol Layout in the context menu.
239 240 241

    To make an item within a layout as wide as possible while respecting the
    given constraints, select the item on the canvas and then select
242 243
    \uicontrol Layout > \uicontrol {Fill Width} in the context menu. To make the item as
    high as possible, select \uicontrol {Fill Height}.
244 245 246

    \section2 Using Split Views

247 248
    From Qt 5.1, you can use the SplitView Qt Quick Control to arrange items
    horizontally or vertically
249 250 251
    with a draggable splitter between each item.


252 253 254 255 256
    \section1 Using States

    Use states and transitions to navigate between screens.

    QML states typically describe user interface configurations, such as the UI
257
    controls, their properties and behavior and the available actions. For
258 259
    example, you can use states to create two screens.

260
    To add states, click the empty slot in the \uicontrol States pane. Then modify the
261 262 263 264 265 266 267 268 269
    new state in the visual editor.

    \image qmldesigner-states.png "States pane"

    The properties that you change in a state are highlighted with blue color.
    In the code editor, you can see the changes recorded as changes to the base
    state.

    To keep the QML code clean, you should create a base state that contains all
270
    the types you will need in the application. You can then create states,
271 272 273 274 275
    in which you hide and show a set of items and modify their properties.
    This allows you to:

    \list

276
        \li Align items on different screens with each other.
277

278
        \li Avoid excessive property changes. If an item is invisible in the
279
            base state, you must define all changes to its child types as
280 281
            property changes, which leads to complicated QML code.

282
        \li Minimize the differences between the base state and the other states
283 284
            to keep the QML code short and readable and to improve performance.

285
        \li Avoid problems when using transitions and animation when changing
286 287 288 289 290 291 292 293
            states.

    \endlist

    To create screens for an application by using states:

    \list 1

294
        \li In the base state, add all items you will need in the
Leena Miettinen's avatar
Leena Miettinen committed
295
            application (1).
296 297
            While you work on one screen, you can click the
            \inlineimage qmldesigner-show-hide-icon.png
298
            icon to hide items on the canvas that are not part of a screen.
299

300
        \li In the \uicontrol States pane, click the empty slot to create a new state
301 302
            and give it a name. For example, \c Normal.

303 304
        \li In the \uicontrol Properties pane (2), deselect the \uicontrol Visibility check box
            or set \uicontrol Opacity to 0 for each item that is not needed in this
305 306
            view. If you specify the setting for the parent item, all child
            items inherit it and are also hidden.
307 308 309

            \image qmldesigner-screen-design.png "Designing screens"

310
        \li Create additional states for each screen and set the visibility
311
            or opacity of the items in the screen.
312

313
        \li To determine which view opens when the application starts, use the
314 315 316 317 318 319 320 321 322 323 324
            code editor to set the state of the root item of the .qml file, as
            specified by the following code snippet:

            \qml
            Item {
                state: "Normal"
            }
            \endqml

        \endlist

325
    \section1 Animating Screens
326 327 328 329 330

    To make movement between states smooth, you can specify transitions. You can
    use different types of animated transitions. For example, you can animate
    changes to property values and colors. You can use rotation animation to
    control the direction of rotation. For more information, see
331
    \l{Animation and Transitions in Qt Quick}.
332

333 334
    You can use the \c ParallelAnimation type to start several animations at
    the same time. Or use the \c SequentialAnimation type to run them one
335 336 337
    after another.

    You can use the code editor to specify transitions. For more information,
338
    see \l{Transition}.
339

340
    \section1 Adding User Interaction Methods
341

342 343
    You can use the following QML types to add basic interaction methods to
    screens:
344 345 346

    \list

347
        \li \l{Flickable}
348 349
            items can be flicked horizontally or vertically.

350
        \li FocusScope
351 352 353
            assists in keyboard focus handling when building reusable QML
            components.

354
        \li MouseArea enables simple mouse handling.
355 356 357

    \endlist

358
    From Qt 5.1, you can also use the following
359
    \l{Qt Quick Controls} to present or receive input from the user:
360 361 362

    \list

363
        \li \l{Button} provides a push button that you can associate with an
364 365
            action.

366
        \li CheckBox provides an option button that can be toggled on
367 368
            (checked) or off (unchecked).

369
        \li ComboBox provides a drop-down list. Add items to the combo box by
370 371 372
            assigning it a ListModel, or a list of strings to the model
            property.

373
        \li GroupBox provides a frame, a title on top, and place for various
374 375
            other controls inside the frame.

376
        \li \l{Label} provides a text label that follows the font and color scheme
377 378
            of the system.

379
        \li ProgressBar indicates the progress of an operation.
380

381
        \li RadioButton provides an option button that can be switched on
382 383
            (checked) or off (unchecked).

384
        \li \l{Slider}
385 386 387 388
            {Slider (Horizontal) and Slider (Vertical)} enable the user to move
            a slider handle along a horizontal or vertical groove and translate
            the handle's position into a value within the specified range.

389
        \li SpinBox enables the user to specify a value by clicking the up or
390 391 392
            down buttons, by pressing up or down on the keyboard, or by entering
            a value in the box.

393 394
        \omit
        Not visible in the item library in 3.2.
395
        \li StatusBar contains status information in your application. It
396
            does not provide a layout of its own, but requires you to position
397
            its contents, for instance by creating a \uicontrol {Row Layout}.
398
        \endomit
399

400
        \li TextArea displays multiple lines of editable formatted text.
401

402
        \li TextField displays a single line of editable plain text.
403

404 405
        \omit
        Not visible in the item library in 3.2.
406
        \li ToolBar provides styling for ToolButton as well as other controls
407 408
            that it can contain. However, it does not provide a layout of its
            own, but requires you to position its contents, for instance by
409
            creating a \uicontrol {Row Layout}.
410
        \endomit
411

412
        \li ToolButton provides a button that is functionally similar to
413
            \uicontrol Button, but that looks more suitable on a \uicontrol {Tool Bar}.
414 415 416 417

    \endlist


418 419 420 421
    \section1 Implementing Application Logic

    A user interface is only a part of an application, and not really useful by itself.
    You can use Qt or JavaScript to implement the application logic. For more information on
422
    using JavaScript, see \l{Integrating QML and JavaScript}.
423 424

    For an example of how to use JavaScript to develop a game, see the
425
    \l{QML Advanced Tutorial}.
426

427
*/