diff options
| -rw-r--r-- | doc/src/qtcreator-toc.qdoc | 9 | ||||
| -rw-r--r-- | doc/src/qtquick/qtquick-app-development.qdoc | 19 | ||||
| -rw-r--r-- | doc/src/qtquick/qtquick-buttons.qdoc | 2 | ||||
| -rw-r--r-- | doc/src/qtquick/qtquick-components.qdoc | 367 | ||||
| -rw-r--r-- | doc/src/qtquick/qtquick-designer.qdoc | 30 | ||||
| -rw-r--r-- | doc/src/qtquick/qtquick-iso-icon-browser.qdoc | 2 | ||||
| -rw-r--r-- | doc/src/qtquick/qtquick-navigator.qdoc | 2 | ||||
| -rw-r--r-- | doc/src/qtquick/qtquick-screens.qdoc | 414 | ||||
| -rw-r--r-- | doc/src/qtquick/qtquick-states.qdoc | 2 |
9 files changed, 367 insertions, 480 deletions
diff --git a/doc/src/qtcreator-toc.qdoc b/doc/src/qtcreator-toc.qdoc index 0a2c2bc10d..119d5f1d92 100644 --- a/doc/src/qtcreator-toc.qdoc +++ b/doc/src/qtcreator-toc.qdoc @@ -88,6 +88,11 @@ \li \l {Creating Qt Quick Projects} \li \l {Qt Quick UI Forms} \li \l {Editing QML Files in Design Mode} + \li \l {Creating Components} + \list + \li \l {Creating Buttons} + \li \l {Creating Scalable Buttons and Borders} + \endlist \li \l {Managing Item Hierarchy} \li \l {Specifying Item Properties} \li \l {Editing PathView Properties} @@ -99,10 +104,6 @@ \li \l{Managing C++ Backend Objects} \endlist \li \l {Adding States} - \li \l {Creating Components} - \li \l {Creating Buttons} - \li \l {Creating Scalable Buttons and Borders} - \li \l {Creating Screens} \li \l {Browsing ISO 7000 Icons} \li \l {Exporting Designs from Graphics Software} \li \l {Using QML Modules with Plugins} diff --git a/doc/src/qtquick/qtquick-app-development.qdoc b/doc/src/qtquick/qtquick-app-development.qdoc index b84dc4187d..be910acc31 100644 --- a/doc/src/qtquick/qtquick-app-development.qdoc +++ b/doc/src/qtquick/qtquick-app-development.qdoc @@ -56,6 +56,12 @@ \uicontrol {Text Editor} in the Design mode to develop Qt Quick applications. + \li \l {Creating Components} + + You can use basic QML types to create your own components that you + can combine with ready-made Qt Quick Controls 2 and Layouts + (available since Qt 5.7). + \li \l {Managing Item Hierarchy} You can manage the items in the current QML file and their @@ -76,16 +82,11 @@ You can connect objects to signals, specify dynamic properties for objects, and create bindings between the properties of two objects. - \li \l {Creating Components} - - You can use basic QML types to create your own components that you - can combine with ready-made Qt Quick Controls 2 and Layouts - (available since Qt 5.7). - \li \l {Creating Screens} + \li \l {Adding States} - You can combine basic QML types with ready-made Qt Quick Controls 2, - Dialogs, and Layouts (available since Qt 5.7) to create screens. You - can use states and transitions to navigate between screens. + You can use states to describe user interface configurations, such + as the UI controls, their properties and behavior, and the available + actions. \li \l {Browsing ISO 7000 Icons} diff --git a/doc/src/qtquick/qtquick-buttons.qdoc b/doc/src/qtquick/qtquick-buttons.qdoc index b924e801da..b11d1c08a2 100644 --- a/doc/src/qtquick/qtquick-buttons.qdoc +++ b/doc/src/qtquick/qtquick-buttons.qdoc @@ -118,7 +118,7 @@ \contentspage {Qt Creator Manual} \previouspage quick-buttons.html \page quick-scalable-image.html - \nextpage quick-screens.html + \nextpage qtquick-navigator.html \title Creating Scalable Buttons and Borders diff --git a/doc/src/qtquick/qtquick-components.qdoc b/doc/src/qtquick/qtquick-components.qdoc index 31af869be8..d71ece963a 100644 --- a/doc/src/qtquick/qtquick-components.qdoc +++ b/doc/src/qtquick/qtquick-components.qdoc @@ -32,7 +32,7 @@ /*! \contentspage {Qt Creator Manual} - \previouspage quick-states.html + \previouspage creator-using-qt-quick-designer.html \page quick-components.html \nextpage quick-buttons.html @@ -42,43 +42,364 @@ that you can re-use in other QML files. A component is like a black box; it interacts with the outside world through properties, signals, and slots, and is generally defined in its own QML file. You can import components to - screens and applications. + applications. + + The \uicontrol {Library} pane lists the available QML types, UI + components, resources, and imports. + + \image qmldesigner-qml-components.png "QML Components" + + The \uicontrol {QML Types} tab displays the QML types grouped by category: + your own QML components, basic types, layouts, positioner types, and views. + + Sets of UI components with the look and feel of a particular mobile device + platform have been defined for Qt Quick 1. Since Qt 5.1, ready-made Qt + Quick Controls, Dialogs, and Layouts are available for creating user + interfaces using Qt Quick 2. The components and controls are based on + standard QML types. To view the components and controls in the + \uicontrol {Library}, import the component sets in \uicontrol Imports. + + The \uicontrol {Qt Quick Application} wizards for a particular platform add + the import statements automatically. You can remove import statements in + \uicontrol Imports + + \uicontrol {Resources} displays the images and other files that you copy + to the project folder (to the same subfolder as the QML files). + + \section1 Adding Components to Designs + + \image qmldesigner-visual-editor.png "Design mode" + + \list 1 + \li Drag and drop components from the \uicontrol Library (2) to the + \uicontrol Navigator (3) or \uicontrol {Form Editor} (1). + \li Select components in the \uicontrol Navigator to edit their + properties in the \uicontrol Properties pane (4). For more + information, see \l {Specifying Item Properties}. + \li Connect components to signals or create bindings between components + in the \uicontrol Connections pane (5). For more information, see + \l{Adding Connections}. + \li Add states to apply sets of changes to the properties of one or + several components in the \uicontrol States pane (6). For more + information, see \l{Adding States}. + \endlist + + \section1 Using Basic QML Types You can use the following QML types to create components: \list + \li \l [QML]{BorderImage}{Border Image} uses an image as a border or + background. + \li \l [QML]{Image} adds a bitmap to the scene. You can stretch and + tile images. + \li \l [QML]{Item} is the most basic of all visual types in QML. Even + though it has no visual appearance, it defines all the properties + that are common across visual types, such as the x and y position, + width and height, anchoring, and key handling. + \li \l [QML]{Rectangle} adds a rectangle that is painted with a solid + fill color and an optional border. You can use the radius property + to create rounded rectangles. + \li \l [QML]{Text} adds formatted read-only text. + \li \l [QML]{TextEdit}{Text Edit} adds a single line of editable + formatted text that can be validated. + \li \l [QML]{TextInput}{Text Input} adds a single line of editable + plain text that can be validated. + \endlist - \li \l [QML]{BorderImage}{Border Image} uses an image as a border or background. + \section1 Using Data Models - \li \l [QML]{Image} - adds a bitmap to the scene. You can stretch and tile images. + You can create the following types of views to organize items provided by + \l{Models and Views in Qt Quick}{data models}: - \li \l [QML]{Item} - is the most basic of all visual types in QML. Even though it has no - visual appearance, it defines all the properties that are common - across visual types, such as the x and y position, width and height, - anchoring, and key handling. + \list + \li \l{GridView}{Grid View} provides a grid vizualization of a model. + \li \l{ListView}{List View} provides a list vizualization of a model. + \li \l{PathView}{Path View} visualizes the contents of a model along a + path. + \endlist - \li \l [QML]{Rectangle} - adds a rectangle that is painted with a solid fill color and an - optional border. You can also use the radius property to create - rounded rectangles. + When you add a \l{GridView}{Grid View}, \l{ListView}{List View}, or + \l{PathView}{Path View}, the ListModel and the delegate component that + creates an instance for each item in the model are added automatically. + You can edit item properties in the \uicontrol Properties pane or + in the \uicontrol {Text Editor}. You can also replace the default model and + delegate with other, more complex models and delegates in the + \uicontrol {Text Editor}. - \li \l [QML]{Text} adds formatted read-only text. + \section1 Positioning Items on Screens + + 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, + \l{Important Concepts In Qt Quick - Positioning#manual-positioning} + {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{Organizing Items} + \endlist + + \section2 Setting Bindings + + \l{Positioning with Bindings} {Property binding} is a declarative way of + specifying the value of a property. Binding allows a property value to be + expressed as a JavaScript expression 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 the Design mode, select the \uicontrol Nut menu next to + a property, and then select \uicontrol {Set Binding}. + + \image qmldesigner-set-expression.png "Type properties context menu" + + The \uicontrol {Binding Editor} supports code completion. Start typing a + string and press \key Ctrl+Space to display a list of properties, IDs, and + code snippets. When you enter a period (.) after a property name, a list of + available values is displayed. Press \key Enter to accept the first + suggestion in the list and to complete the code. + + \image qmldesigner-binding-editor.png "Binding Editor" + + To remove bindings, select \uicontrol Reset in the context menu. + + You can set bindings also in the \uicontrol Connections view. For more + information, see \l {Adding Bindings Between Properties}. + + For more information on the JavaScript environment provided by QML, see + \l{Integrating QML and JavaScript}. + + Bindings are a black box for the Design mode 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 + + In an \l{Important Concepts In Qt Quick - Positioning#anchors} + {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. + + In the \uicontrol Layout pane you can set anchors and margins for items. To + set 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" + + For convenience, you can click the \inlineimage anchor_fill.png + (\uicontrol {Fill to Parent}) toolbar button to apply fill anchors to an + item and the \inlineimage qtcreator-anchors-reset-icon.png + (\uicontrol {Reset Anchors}) button to reset the anchors to their saved + state. + + You can specify the baseline anchor in the \uicontrol {Text Editor} in the + Design mode. - \li \l [QML]{TextEdit}{Text Edit} - adds a single line of editable formatted text that can be validated. + 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 use the anchor buttons. Select a sibling of the item in the + \uicontrol Target field to anchor to it, instead. - \li \l [QML]{TextInput}{Text Input} - adds a single line of editable plain text that can be validated. + 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. - \omit - \li \l{WebView} adds web content to a canvas. - \endomit + In the following image, \uicontrol{Rectangle 2} is anchored to + \uicontrol {Rectangle 1} on its left and to the bottom of its parent. + \image qmldesigner-anchors.png "Anchoring sibling items" + + The anchors for \uicontrol{Rectangle 2} are specified as follows in code: + + \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 layouts or absolute positioning. + + \section2 Using Positioners + + \l{Important Concepts In Qt Quick - Positioning#positioners} + {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: + + \list + \li \l[QML] {Column} arranges its child items vertically. + \li \l[QML] {Row} arranges its child items horizontally. + \li \l[QML] {Grid} + arranges its child items so that they are aligned in a grid and + are not overlapping. + \li \l[QML] {Flow} + arranges its child items side by side, wrapping as necessary. + \endlist + + To lay out several items in a \uicontrol Column, \uicontrol Row, + \uicontrol Grid, or \uicontrol Flow, select the items on the canvas, and + then select \uicontrol Layout in the context menu. + + \section2 Using Layouts + + Since 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 + declarative interface. They are well suited for resizable user interfaces. + + You can use the following layout types to arrange items on screens: + + \list + \li \l{Layout} provides attached properties for items pushed onto a + \uicontrol {Column Layout}, \uicontrol {Row Layout}, or + \uicontrol {Grid Layout}. + \li \l{ColumnLayout}{Column Layout} provides a grid layout with only + one column. + \li \l{RowLayout}{Row Layout} provides a grid layout with only one row. + \li \l{GridLayout}{Grid Layout} provides a way of dynamically arranging + items in a grid. + \li \l{StackLayout}{Stack Layout} provides a stack of items where only + one item is visible at a time. + \endlist + + To lay out several items in a \uicontrol {Column Layout}, + \uicontrol {Row Layout}, \uicontrol {Grid Layout}, or + \uicontrol {Stack Layout}, select the items in the \uicontrol {Form Editor}, + and then select \uicontrol Layout in the context menu. + + You can also click the \inlineimage column.png + (\uicontrol {Column Layout}), \inlineimage row.png + (\uicontrol {Row Layout}), and \inlineimage grid.png + (\uicontrol {Grid Layout}) toolbar buttons to apply + layouts to the selected items. + + 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 + \uicontrol Layout > \uicontrol {Fill Width} in the context menu. To + make the item as high as possible, select \uicontrol {Fill Height}. + + \section2 Editing Stack Layouts + + \image qtquick-designer-stacked-view.png + + To add items to a \uicontrol {Stack Layout}, select the + \inlineimage plus.png + button next to the type name in the \uicontrol {Form Editor}. To move + between items, select the \inlineimage prev.png + (\uicontrol Previous) and \inlineimage next.png + (\uicontrol Next) buttons. + + To add a tab bar to a stack layout, select \uicontrol {Stacked Container} > + \uicontrol {Add Tab Bar}. + + To raise or lower the stacking order of an item, select + \uicontrol {Stacked Container} > \uicontrol {Increase Index} or + \uicontrol {Decrease Index}. + + \section2 Organizing Items + + Since Qt 5.7, you can use the following \l{Qt Quick Controls 2} types to + organize items on screens: + + \list + \li \l [QtQuickControls2]{Frame} places a logical group of controls + within a visual frame. + \li \l [QtQuickControls2]{GroupBox}{Group Box} is used to lay out a + logical group of controls together, within a titled visual frame. + \li \l [QtQuickControls2]{Label} is a text label with inherited styling + and font. + \li \l [QtQuickControls2]{PageIndicator}{Page Indicator} indicates the + currently active page. + \li \l [QtQuickControls2]{Pane} provides a background matching with the + application style and theme. + \endlist + + \section1 Adding User Interaction Methods + + You can use the following QML types to add basic interaction methods to + screens: + + \list + \li \l{Flickable} + items can be flicked horizontally or vertically. + \li \l{FocusScope}{Focus Scope} + assists in keyboard focus handling when building reusable QML + components. + \li \l [QML]{MouseArea}{Mouse Area} enables simple mouse handling. + \endlist + + Since Qt 5.7, you can also use the following \l{Qt Quick Controls 2} types + to inform users about the progress of the application or to gather input + from the user: + + \list + \li \l [QtQuickControls2]{BusyIndicator}{Busy Indicator} indicates + activity while content is being loaded. + \li \l [QtQuickControls2]{Button} provides a push button that you can + associate with an action. + \li \l [QtQuickControls2]{CheckBox}{Check Box} provides an option button + that can be toggled on (checked) or off (unchecked). + \li \l [QtQuickControls2]{CheckDelegate}{Check Delegate} presents an + item delegate that can be toggled on (checked) or off (unchecked). + \li \l [QtQuickControls2]{ComboBox}{Combo Box} is a combined button and + popup list that is populated by using a data model. + \li \l [QtQuickControls2]{Dial} is a circular dial that is rotated to + set a value. + \li \l [QtQuickControls2]{ItemDelegate}{Item Delegate} is a standard + view item that can be used in various views and controls. + \li \l [QtQuickControls2]{ProgressBar}{Progress Bar} indicates the + progress of an operation. + \li \l [QtQuickControls2]{RadioButton}{Radio Button} provides an option + button that can be switched on (checked) or off (unchecked). + \li \l [QtQuickControls2]{RadioDelegate}{Radio Delegate} presents an + item delegate that can be toggled on (checked) or off (unchecked). + \li \l [QtQuickControls2]{Slider} selects a value by sliding a handle + along a track. + \li \l [QtQuickControls2]{SpinBox}{Spin Box} enables the user to specify + a value by clicking the up or down buttons, by pressing up or down + on the keyboard, or by entering a value in the box. + \li \l [QtQuickControls2]{Switch} is an option button that can be + toggled on or off. + \li \l [QtQuickControls2]{TextArea}{Text Area} displays multiple lines + of editable formatted text. + \li \l [QtQuickControls2]{TextField}{Text Field} displays a single line + of editable plain text. + \li \l [QtQuickControls2]{ToolBar}{Tool Bar} is a container of + application-wide and context sensitive actions and controls, such as + navigation buttons and search fields. + \li \l [QtQuickControls2]{ToolButton}{Tool Button} is a button + that is functionally similar to \uicontrol Button, but provides a + look that is more suitable for a \uicontrol {Tool Bar}. + \li \l [QtQuickControls2]{Tumbler} is a spinnable wheel of items that + can be selected. \endlist - \section1 Using Qt Quick Controls + \section1 History of Qt Quick Controls In Qt 4, ready-made Qt Quick 1 Components were provided for creating screens with a native look and feel for a particular target platform. diff --git a/doc/src/qtquick/qtquick-designer.qdoc b/doc/src/qtquick/qtquick-designer.qdoc index 92d3457fb7..82ee4f72ad 100644 --- a/doc/src/qtquick/qtquick-designer.qdoc +++ b/doc/src/qtquick/qtquick-designer.qdoc @@ -33,7 +33,7 @@ \contentspage {Qt Creator Manual} \previouspage creator-quick-ui-forms.html \page creator-using-qt-quick-designer.html - \nextpage qtquick-navigator.html + \nextpage quick-components.html \title Editing QML Files in Design Mode @@ -65,7 +65,8 @@ \li \uicontrol {Library} (2) displays the building blocks that you can use to design applications: predefined QML types, your own QML components, or Qt Quick Controls 2 that you import to the - project, and other resources. + project, and other resources. For more information, see + \l {Creating Components}. \li \uicontrol {Navigator} (3) displays the items in the current QML file as a tree structure. For more information, see @@ -99,33 +100,10 @@ \endlist - \section1 QML Type Library - - The \uicontrol {Library} enables you to select QML types, UI components, and - resources, as well as to manage imports. - - \uicontrol {QML Types} displays the QML types grouped by category: your own QML - components, basic types, layouts, positioner types, and views. - - Sets of UI components with the look and feel of a particular mobile device - platform have been defined for Qt Quick 1. Since Qt 5.1, ready-made Qt - Quick Controls, Dialogs, and Layouts are available for creating user - interfaces using Qt Quick 2.1. The components and controls are based on - standard QML types. To view the components and controls in the - \uicontrol {Library}, import the component sets in \uicontrol Imports. - - The \uicontrol {Qt Quick Application} wizards for a particular platform add the - import statements automatically. You can remove import statements in - \uicontrol Imports - - \image qmldesigner-qml-components.png "QML Components" - - \uicontrol {Resources} displays the images and other files that you copy - to the project folder (to the same subfolder as the QML files). - \section1 Snapping to Parent and Sibling Items You design applications on the canvas by placing items on it. + When you are working on a design, you can use snapping to align items on the canvas. Click the \inlineimage snapping.png button to have the items snap to their parent or sibling items. Snapping diff --git a/doc/src/qtquick/qtquick-iso-icon-browser.qdoc b/doc/src/qtquick/qtquick-iso-icon-browser.qdoc index e8f918ca26..a8e55d2ae6 100644 --- a/doc/src/qtquick/qtquick-iso-icon-browser.qdoc +++ b/doc/src/qtquick/qtquick-iso-icon-browser.qdoc @@ -25,7 +25,7 @@ /*! \contentspage {Qt Creator Manual} - \previouspage quick-screens.html + \previouspage quick-states.html \page qtquick-iso-icon-browser.html \nextpage quick-export-to-qml.html diff --git a/doc/src/qtquick/qtquick-navigator.qdoc b/doc/src/qtquick/qtquick-navigator.qdoc index 21e26a7671..1b4f211ff5 100644 --- a/doc/src/qtquick/qtquick-navigator.qdoc +++ b/doc/src/qtquick/qtquick-navigator.qdoc @@ -25,7 +25,7 @@ /*! \contentspage {Qt Creator Manual} - \previouspage creator-using-qt-quick-designer.html + \previouspage quick-scalable-image.html \page qtquick-navigator.html \nextpage qtquick-properties.html diff --git a/doc/src/qtquick/qtquick-screens.qdoc b/doc/src/qtquick/qtquick-screens.qdoc deleted file mode 100644 index ec0dd9ced7..0000000000 --- a/doc/src/qtquick/qtquick-screens.qdoc +++ /dev/null @@ -1,414 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the Qt Creator documentation. -** -** 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. -** -** GNU Free Documentation License Usage -** 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. 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. -** -****************************************************************************/ - -// ********************************************************************** -// 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. -// ********************************************************************** - -/*! - - \contentspage {Qt Creator Manual} - \previouspage quick-scalable-image.html - \page quick-screens.html - \nextpage qtquick-iso-icon-browser.html - - \title Creating Screens - - You can use predefined QML types and your own components to create - screens. Typically, the main QML file in a Qt Quick project specifies the - main window of an application. - - The QML files in the project folder are displayed in \uicontrol {QML Components} - in the \uicontrol Library. - - \section1 Adding Components to Screens - - \list 1 - - \li Drag and drop components from the \uicontrol Library to the - \uicontrol Navigator or \uicontrol {Form Editor}. - - \li Select components in the \uicontrol Navigator to edit their - properties in the \uicontrol Properties pane. - - For example, you can anchor components to a position on the screen. - - \endlist - - For more information about the ready-made components available, see - \l {Using Qt Quick Controls}. - - \section1 Using Data Models - - You can create the following types of views to organize items provided by - \l{Models and Views in Qt Quick}{data models}: - - \list - - \li \l{GridView}{Grid View} provides a grid vizualization of a model. - - \li \l{ListView}{List View} provides a list vizualization of a model. - - \li \l{PathView}{Path View} visualizes the contents of a model along a - path. - - \endlist - - When you add a \l{GridView}{Grid View}, \l{ListView}{List View}, or - \l{PathView}{Path View}, the ListModel and the delegate component that - creates an instance for each item in the model are added automatically. - You can edit item properties in the \uicontrol Properties pane or - in the \uicontrol {Text Editor}. You can also replace the default model and - delegate with other, more complex models and delegates in the - \uicontrol {Text Editor}. - - \section1 Positioning Items on Screens - - 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, - \l{Important Concepts In Qt Quick - Positioning#manual-positioning} - {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{Organizing Items} - - \endlist - - \section2 Setting Bindings - - \l{Positioning with Bindings} - {Property binding} is a declarative way of specifying the value of a property. - Binding allows a property value to be expressed as a JavaScript expression - 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 the Design mode, click the circle icon next to a property to - open a context menu, and select \uicontrol {Set Binding}. - - \image qmldesigner-set-expression.png "Type properties context menu" - - The \uicontrol {Binding Editor} supports code completion. Start typing a - string and press \key Ctrl+Space to display a list of properties, IDs, and - code snippets. When you enter a period (.) after a property name, a list of - available values is displayed. Press \key Enter to accept the first - suggestion in the list and to complete the code. - - \image qmldesigner-binding-editor.png "Binding Editor" - - To remove bindings, select \uicontrol Reset in the context menu. - - You can set bindings also in the \uicontrol Connections view. For more - information, see \l {Adding Bindings Between Properties}. - - For more information on the JavaScript environment provided by QML, see - \l{Integrating QML and JavaScript}. - - Bindings are a black box for the Design mode 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 - - In an \l{Important Concepts In Qt Quick - Positioning#anchors} - {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. - - In the \uicontrol Layout pane you can set anchors and margins for items. To set - 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" - - For convenience, you can click the \inlineimage anchor_fill.png - (\uicontrol {Fill to Parent}) toolbar button to apply fill anchors to an - item and the \inlineimage qtcreator-anchors-reset-icon.png - (\uicontrol {Reset Anchors}) button to reset the anchors to their saved - state. - - You can specify the baseline anchor in the \uicontrol {Text Editor} in the - Design mode. - - 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 - use the anchor buttons. Select a sibling of the item in the \uicontrol Target - 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. - - In the following image, \uicontrol{Rectangle 2} is anchored to \uicontrol{Rectangle 1} - on its left and to the bottom of its parent. - - \image qmldesigner-anchors.png "Anchoring sibling items" - - The anchors for \uicontrol{Rectangle 2} are specified as follows in code: - - \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 - - \l{Important Concepts In Qt Quick - Positioning#positioners} - {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: - - \list - - \li \l[QML] {Column} arranges its child items vertically. - - \li \l[QML] {Row} arranges its child items horizontally. - - \li \l[QML] {Grid} - arranges its child items so that they are aligned in a grid and - are not overlapping. - - \li \l[QML] {Flow} - arranges its child items side by side, wrapping as necessary. - - \endlist - - To lay out several items in a \uicontrol Column, \uicontrol Row, - \uicontrol Grid, or \uicontrol Flow, select the items on the canvas, and - then select \uicontrol Layout in the context menu. - - \section2 Using Layouts - - 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 - declarative interface. They are well suited for resizable user interfaces. - - You can use the following layout types to arrange items on screens: - - \list - - \li \l{Layout} provides attached properties for items pushed onto a - \uicontrol {Column Layout}, \uicontrol {Row Layout}, or \uicontrol {Grid Layout}. - - \li \l{ColumnLayout}{Column Layout} provides a grid layout with only one - column. - - \li \l{RowLayout}{Row Layout} provides a grid layout with only one row. - - \li \l{GridLayout}{Grid Layout} provides a way of dynamically arranging - items in a grid. - - \li \l{StackLayout}{Stack Layout} provides a stack of items where only - one item is visible at a time. - - \endlist - - To lay out several items in a \uicontrol {Column Layout}, \uicontrol {Row Layout}, - \uicontrol {Grid Layout}, or \uicontrol {Stack Layout}, select the items in - the \uicontrol {Form Editor}, and then select \uicontrol Layout in the - context menu. - - You can also click the \inlineimage column.png - (\uicontrol {Column Layout}), \inlineimage row.png - (\uicontrol {Row Layout}), and \inlineimage grid.png - (\uicontrol {Grid Layout}) toolbar buttons to apply layouts to the selected - items. - - 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 - \uicontrol Layout > \uicontrol {Fill Width} in the context menu. To make the item as - high as possible, select \uicontrol {Fill Height}. - - \section3 Editing Stack Layouts - - \image qtquick-designer-stacked-view.png - - To add items to a \uicontrol {Stack Layout}, select the - \inlineimage plus.png - button next to the type name in the \uicontrol {Form Editor}. To move - between items, select the \inlineimage prev.png - (\uicontrol Previous) and \inlineimage next.png - (\uicontrol Next) buttons. - - To add a tab bar to a stack layout, select \uicontrol {Stacked Container} > - \uicontrol {Add Tab Bar}. - - To raise or lower the stacking order of an item, select - \uicontrol {Stacked Container} > \uicontrol {Increase Index} or - \uicontrol {Decrease Index}. - - \section2 Organizing Items - - From Qt 5.7, you can use the following \l{Qt Quick Controls 2} types to - organize items on screens: - - \list - - \li \l [QtQuickControls2]{Frame} places a logical group of controls - within a visual frame. - - \li \l [QtQuickControls2]{GroupBox}{Group Box} is used to lay out a - logical group of controls together, within a titled visual frame. - - \li \l [QtQuickControls2]{Label} is a text label with inherited styling - and font. - - \li \l [QtQuickControls2]{PageIndicator}{Page Indicator} indicates the - currently active page. - - \li \l [QtQuickControls2]{Pane} provides a background matching with the - application style and theme. - - \endlist - - \section1 Adding User Interaction Methods - - You can use the following QML types to add basic interaction methods to - screens: - - \list - - \li \l{Flickable} - items can be flicked horizontally or vertically. - - \li \l{FocusScope}{Focus Scope} - assists in keyboard focus handling when building reusable QML - components. - - \li \l [QML]{MouseArea}{Mouse Area} enables simple mouse handling. - - \endlist - - Since Qt 5.7, you can also use the following \l{Qt Quick Controls 2} types - to inform users about the progress of the application or to gather input - from the user: - - \list - - \li \l [QtQuickControls2]{BusyIndicator}{Busy Indicator} indicates - activity while content is being loaded. - - \li \l [QtQuickControls2]{Button} provides a push button that you can - associate with an action. - - \li \l [QtQuickControls2]{CheckBox}{Check Box} provides an option button - that can be toggled on (checked) or off (unchecked). - - \li \l [QtQuickControls2]{CheckDelegate}{Check Delegate} presents an - item delegate that can be toggled on (checked) or off (unchecked). - - \li \l [QtQuickControls2]{ComboBox}{Combo Box} is a combined button and - popup list that is populated by using a data model. - - \li \l [QtQuickControls2]{Dial} is a circular dial that is rotated to - set a value. - - \li \l [QtQuickControls2]{ItemDelegate}{Item Delegate} is a standard - view item that can be used in various views and controls. - - \li \l [QtQuickControls2]{ProgressBar}{Progress Bar} indicates the - progress of an operation. - - \li \l [QtQuickControls2]{RadioButton}{Radio Button} provides an option - button that can be switched on (checked) or off (unchecked). - - \li \l [QtQuickControls2]{RadioDelegate}{Radio Delegate} presents an - item delegate that can be toggled on (checked) or off (unchecked). - - \li \l [QtQuickControls2]{Slider} selects a value by sliding a handle - along a track. - - \li \l [QtQuickControls2]{SpinBox}{Spin Box} enables the user to specify - a value by clicking the up or down buttons, by pressing up or down - on the keyboard, or by entering a value in the box. - - \li \l [QtQuickControls2]{Switch} is an option button that can be - toggled on or off. - - \li \l [QtQuickControls2]{TextArea}{Text Area} displays multiple lines - of editable formatted text. - - \li \l [QtQuickControls2]{TextField}{Text Field} displays a single line - of editable plain text. - - \li \l [QtQuickControls2]{ToolBar}{Tool Bar} is a container of - application-wide and context sensitive actions and controls, such as - navigation buttons and search fields. - - \li \l [QtQuickControls2]{ToolButton}{Tool Button} is a button - that is functionally similar to \uicontrol Button, but provides a - look that is more suitable for a \uicontrol {Tool Bar}. - - \li \l [QtQuickControls2]{Tumbler} is a spinnable wheel of items that - can be selected. - - \endlist - - \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 - using JavaScript, see \l{Integrating QML and JavaScript}. - - For an example of how to use JavaScript to develop a game, see the - \l{QML Advanced Tutorial}. - -*/ diff --git a/doc/src/qtquick/qtquick-states.qdoc b/doc/src/qtquick/qtquick-states.qdoc index b13f656aaf..d9a6ba95e4 100644 --- a/doc/src/qtquick/qtquick-states.qdoc +++ b/doc/src/qtquick/qtquick-states.qdoc @@ -27,7 +27,7 @@ \contentspage {Qt Creator Manual} \previouspage quick-connections-backend.html \page quick-states.html - \nextpage quick-components.html + \nextpage qtquick-iso-icon-browser.html \title Adding States |