feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: Move information about Qt Quick Controls to "Creating Components"

Browse Source 
Move the topic up in the hierarchy. Will remove "Creating Screens" in
a follow-up commit.

Change-Id: I0de2bdc4706ab0cce13f5772006126b291e76b97
Reviewed-by: Tim Jenssen <tim.jenssen@qt.io>
This commit is contained in:
Leena Miettinen
2018-07-11 13:36:37 +02:00
parent a30e9e0f9a
commit f18d2ded9b
9 changed files with 375 additions and 488 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
doc/src/qtcreator-toc.qdoc
View File

@@ -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}

19
doc/src/qtquick/qtquick-app-development.qdoc
View File

@@ -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}
\li \l {Adding States}
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}
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}

2
doc/src/qtquick/qtquick-buttons.qdoc
View File

@@ -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

383
doc/src/qtquick/qtquick-components.qdoc
View File

@@ -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 also use the radius property to create
rounded rectangles.
\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.
\omit
\li \l{WebView} adds web content to a canvas.
\endomit
\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
\section1 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, 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.
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 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 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.

30
doc/src/qtquick/qtquick-designer.qdoc
View File

@@ -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

2
doc/src/qtquick/qtquick-iso-icon-browser.qdoc
View File

@@ -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

2
doc/src/qtquick/qtquick-navigator.qdoc
View File

@@ -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

414
doc/src/qtquick/qtquick-screens.qdoc
View File

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

2
doc/src/qtquick/qtquick-states.qdoc
View File

@@ -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