Doc: Restructure information about Connections View

- Add a topic that summarizes the Connections View tabs
- Hide some technical detail in the instructions
- Make "Adding Connections" a collection topic
- Fix terminology to use "component" instead of "object".
  "item", or "QML type"

Task-number: QDS-3771
Change-Id: I0b0d66cb50d8ecc7dbc812ef57918ffafb64cd8c
Reviewed-by: Thomas Hartmann <thomas.hartmann@qt.io>
This commit is contained in:
Leena Miettinen
2021-03-04 13:16:36 +01:00
parent 4b1bb9c0fc
commit 706b9ceedb
19 changed files with 263 additions and 133 deletions

Binary file not shown.

Before

Width:  |  Height:  |  Size: 5.1 KiB

After

Width:  |  Height:  |  Size: 3.7 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.1 KiB

After

Width:  |  Height:  |  Size: 4.1 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 5.6 KiB

After

Width:  |  Height:  |  Size: 4.4 KiB

View File

@@ -96,6 +96,7 @@
\li \l{Library}
\li \l{Navigator}
\li \l{Properties}
\li \l{Connection View}
\li \l{Transition Editor}
\li \l{Timeline}
\li \l{Curve Editor}
@@ -128,9 +129,9 @@
\endlist
\li \l{Adding Connections}
\list
\li \l{Connecting Objects to Signals}
\li \l{Specifying Dynamic Properties}
\li \l{Connecting Components to Signals}
\li \l{Adding Bindings Between Properties}
\li \l{Specifying Dynamic Properties}
\li \l{Managing C++ Backend Objects}
\endlist
\li \l {Adding States}

View File

@@ -1,6 +1,6 @@
/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
@@ -84,6 +84,14 @@
different type.
\endtable
\if defined(qtdesignstudio)
Alternatively, you can use \uicontrol {And Operator},
\uicontrol {Or Operator}, and \uicontrol {Not Operator}
components to bind property values using the boolean AND,
OR, and NOT operator. For more information, see \l{Logic Helpers}.
\endif
In addition, you can use arithmetic operators to compare numbers before
checks. However, we recommend that you create separate properties for this
purpose whenever possible.

View File

@@ -248,7 +248,7 @@
\list
\li \l{Adding States}
\li \l{Connecting Objects to Signals}
\li \l{Connecting Components to Signals}
\endlist
\section1 Animating Transitions

View File

@@ -76,7 +76,7 @@
can define an area smaller or larger than the parent. Several controls,such
as \l {Button}{buttons}, contain a mouse area.
A mouse area emits \l{Connecting Objects to Signals}{signals} in response
A mouse area emits \l{Connecting Components to Signals}{signals} in response
to different mouse events:
\list
@@ -437,7 +437,7 @@
\section2 Button Signals
A button emits the \c clicked() signal when it is activated by users.
\l{Connecting Objects to Signals}{Connect to this signal} to perform
\l{Connecting Components to Signals}{Connect to this signal} to perform
the button's action. Buttons provide the following additional signals:
\c canceled(), \c doubleClicked(), \c pressed(), \c released(), and
\c pressAndHold() for long presses.

View File

@@ -90,7 +90,7 @@
\li To enable users to interact with components, connect the components
to signals in the \uicontrol Connections view. For example, you can
specify what happens when a component is clicked.
For more information, see \l{Connecting Objects to Signals}.
For more information, see \l{Connecting Components to Signals}.
\image qmldesigner-connections.png "Connections view Connections tab"
\li To dynamically change the behavior of an object when another object
changes, create bindings between components in the

View File

@@ -1,6 +1,6 @@
/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
@@ -25,43 +25,44 @@
/*!
\page quick-property-bindings.html
\previouspage quick-dynamic-properties.html
\if defined(qtdesignstudio)
\nextpage quick-states.html
\else
\nextpage quick-connections-backend.html
\endif
\previouspage quick-signals.html
\nextpage quick-dynamic-properties.html
\title Adding Bindings Between Properties
To dynamically change the behavior of an object, you can create a \e binding
between the properties of two objects. To create a property binding, a
property is assigned a JavaScript expression that evaluates to the desired
value. At its simplest, a binding may be a reference to another property.
For example, the height of an object can be bound to the height of its
parent, so that when the parent height changes, the object height is
To dynamically change the behavior of a component, you can create a
\e binding between the properties of two components. To create a property
binding, a property is assigned a JavaScript expression that evaluates to
the desired value. Behind the scenes, the variables in the binding
expression are monitored. When a change is detected, the binding
expression is re-evaluated and the new result is applied to the property.
At its simplest, a binding may be a reference to another property.
For example, the height of a component can be bound to the height of its
parent, so that when the parent height changes, the component height is
adjusted automatically.
For more information about the use of property bindings, see
\l{Property Binding}.
You can create bindings between objects in the \uicontrol Connections view.
You can create bindings between components in \uicontrol Bindings.
\image qmldesigner-bindings.png
To bind a property of an object to the property of another object:
To bind a property of a component to the property of another component:
\list 1
\li In the \uicontrol {Connections} view, select the
\uicontrol {Bindings} tab.
\li Select \uicontrol View > \uicontrol Views >
\uicontrol {Connection view} > \uicontrol {Bindings}.
\li Select the \inlineimage plus.png
(\uicontrol Add) button to add a binding for the currently selected
item. The ID is displayed in the \uicontrol Item column.
component. The component ID is displayed in the \uicontrol Item
column.
\li Double-click the value in the \uicontrol Property column to select
the property to bind to a source property.
\li Double-click the value in the \uicontrol {Source Item} column to
select the object whose property you want to use to determine the
behavior of the target object.
select the component whose property you want to use to determine the
behavior of the target component.
\li Double-click the value in the \uicontrol {Source Property} column
to select the property to bind the target property to.
\endlist
@@ -72,6 +73,17 @@
\image qmldesigner-binding-editor.png "Binding Editor"
For examples of creating property bindings, see:
\list
\li \l{Using States to Change Component Property Values}
\if defined(qtdesignstudio)
\li \l{Exporting Properties}
\else
\li \l{Moving the Bubble} in \l{Creating a Mobile Application}
\endif
\endlist
For more information, watch the following video:
\youtube UfvA04CIXv0

View File

@@ -24,40 +24,45 @@
****************************************************************************/
/*!
\previouspage quick-signals.html
\page quick-dynamic-properties.html
\nextpage quick-property-bindings.html
\previouspage quick-property-bindings.html
\if defined(qtdesignstudio)
\nextpage quick-states.html
\else
\nextpage quick-connections-backend.html
\endif
\title Specifying Dynamic Properties
Each predefined QML type has a set of predefined properties that you can
specify values for. You can add custom properties that would not otherwise
exist for a particular type. You bind the properties to dynamic expressions
to define global properties for an object that can be read by other objects.
For example, you can specify global properties for the root object that you
can use in the child objects.
Each preset \l{glossary-component}{component} has a set of preset properties
that you can specify values for. You can add custom properties that would
not otherwise exist for a particular \l{Component Types}{component type}.
You bind the properties to dynamic expressions to define global properties
for a component that can be read by other components. For example, you can
specify global properties for the root component that you can use in the
child components.
For example, to specify spacing between UI elements, you could define a
margin for an object of a QML type that does not have a margin property,
and then use bindings to refer to the value of the margin property from
other objects.
margin for a component that does not have a margin property, and then use
\l{Adding Bindings Between Properties}{bindings} to refer to the value of
the margin property from other components.
Similarly, you can add custom properties for your own QML types that are
based on the predefined types.
Similarly, you can add custom properties for your own components that are
based on preset components.
You can add properties for objects in the \uicontrol Connections view,
\uicontrol Properties tab.
You can add properties for components in \uicontrol {Connections View} >
\uicontrol Properties.
\image qmldesigner-dynamicprops.png "Custom properties in Connection View Custom Properties tab"
To add properties for an object:
To add properties for a component:
\list 1
\li Select \uicontrol View > \uicontrol Views >
\uicontrol {Connections View} > \uicontrol {Properties}.
\li Select the \inlineimage plus.png
(\uicontrol Add) button to add a dynamic property for the currently
selected item. The item ID is displayed in the \uicontrol Item
selected component. The component ID is displayed in the \uicontrol Item
column.
\li Double-click the value in the \uicontrol Property column to give a
name to the property. Property names must begin with a lower case
@@ -76,17 +81,19 @@
\image qmldesigner-binding-editor.png "Binding Editor"
The properties you add for a QML type are displayed in the
\uicontrol Properties view when you select a component of
that type in \uicontrol Navigator or \uicontrol {Form Editor}.
The properties you add for a component are displayed in the \l Properties
view when you select a component of that type in \l Navigator or
\l {Form Editor}.
\image qtquick-custom-properties.png "Custom properties in Properties view"
For more information about setting property values in the
\uicontrol Properties view, see \l{Specifying Component Properties}.
\l Properties view, see \l{Specifying Component Properties}.
\if defined(qtcreator)
For an example of using custom properties in an application, see
\l{Creating a Mobile Application}.
\endif
\section1 Supported Property Types

View File

@@ -1,6 +1,6 @@
/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
@@ -26,55 +26,57 @@
/*!
\previouspage qmldesigner-connections.html
\page quick-signals.html
\nextpage quick-dynamic-properties.html
\nextpage quick-property-bindings.html
\title Connecting Objects to Signals
\title Connecting Components to Signals
A signal and handler mechanism enables components to respond to application
events, which are represented by \e signals. When a signal is emitted, the
corresponding \e {signal handler} is invoked to respond to the event by
using scripts or other operations placed in the handler.
To receive a notification when a particular signal is emitted for a
particular object, the object definition should declare a signal handler
particular component, the component definition should declare a signal handler
named \e {on<Signal>} where \e {<Signal>} is the name of the signal, with
the first letter capitalized. The signal handler should contain the
JavaScript code to be executed when the signal handler is invoked.
QML types have predefined signals that are emitted when users interact with
the application. For example, the \l {Mouse Area} type has a
\c clicked signal that is emitted whenever the mouse is
clicked within the area. Since the signal name is \c clicked, the signal
handler for receiving this signal is named \c onClicked.
Components have predefined signals that are emitted when users interact with
the application. For example, the \l {Mouse Area} component has a \c clicked
signal that is emitted whenever the mouse is clicked within the area. Since
the signal name is \c clicked, the signal handler for receiving this signal
is named \c onClicked.
A signal is automatically emitted when the value of a QML property changes.
A signal is automatically emitted when the value of a property changes.
This type of signal is a \e{property change signal} and signal handlers
for these signals are written in the form \c on<Property>Changed, where
\e <Property> is the name of the property, with the first letter
capitalized.
For example, the Mouse Area type has a \c pressed property. To receive a
notification whenever this property changes, you would use a signal handler
For example, the Mouse Area component has a \c pressed property. To receive
a notification whenever this property changes, you would use a signal handler
called \c onPressedChanged.
For more information about signals and signal handlers, see
\l{Signal and Handler Event System}.
To access a signal outside of the object that emits it, you can use the
\l Connections type for connecting to signals of arbitrary objects. A
connections object can receive any signal from its specified target.
You can connect objects to signals that are available to them in the
\uicontrol Connections view.
You can connect components to signals that are available to them in
\uicontrol Connections.
\image qmldesigner-connections.png
To connect objects to signals:
To connect components to signals:
\list 1
\li In the \uicontrol {Connections} view, select the
\uicontrol {Connections} tab.
\li Select \uicontrol View > \uicontrol Views >
\uicontrol {Connection View} > \uicontrol {Connections}.
\li Select the \inlineimage plus.png
(\uicontrol Add) button to add a connection.
\li Double-click the value in the \uicontrol Target column to add the
object to connect to a signal.
component to connect to a signal.
\li Double-click the value in the \uicontrol {Signal Handler} column to
select the signal that the connection will listen to from a list of
all signals available for the object.
all signals available for the component.
\li Double-click the value in the \uicontrol Actions column to specify
the action to perform when the signal is emitted. You use JavaScript
to specify the actions.
@@ -84,6 +86,18 @@
in the context menu to specify the connection in
\uicontrol {Connection Editor}.
\if defined(qtcreator)
For an example of using the \uicontrol {Connections} view, see
\l{Connecting Mouse Clicks to State Changes}.
\else
For examples of using the \uicontrol {Connections} view, see:
\list
\li \l{Connecting Buttons to States} in \l{Log In UI - Part 3}
\li \l{Connecting Buttons to State Changes} in \l{Washing Machine UI}
\endlist
\endif
\section1 Adding Signal Handlers
If a signal handler that you need is not listed in the
@@ -100,43 +114,41 @@
\li Select \uicontrol OK.
\endlist
The added signal handler is automatically \l{Using Qt Quick UI Forms}
The added signal handler is automatically \l{Adding Property Aliases}
{exported as a property}.
\if defined(qtdesignstudio)
\section1 Adding Actions and Assignments
You use the \uicontrol {Connection Editor} to create the JavaScript
expressions for \e actions and \e assignments. An \e action connects
an object to a signal, whereas an \e assignment fetches property values
from another object.
an component to a signal, whereas an \e assignment fetches property values
from another component.
For more information about the logical operators that you can use to
construct conditional expressions, see \l {Summary of Logical Operators}.
To create JavaScript expressions for actions:
\image qtquick-connection-editor-action.png
\list 1
\li Select \uicontrol Action as the type of the connections object.
\li Select the object to connect to a signal.
\li Select \uicontrol {Open Connection Editor} in the context menu
in \uicontrol {Connections}.
\image qtquick-connection-editor-action.png
\li Select \uicontrol Action as the type of the connections component.
\li Select the component to connect to a signal.
\li Select the action to perform when the signal is emitted.
\endlist
To create JavaScript expressions for assignments:
\image qtquick-connection-editor-assignment.png
\list 1
\li Select \uicontrol Assignment as the type of the connections object.
\li Select the target object for the property assignment.
\li Select the property of the target object to assign a value to.
\li Select the source object for the property assignment.
\li Select the property of the source object to fetch the value from.
\li Select \uicontrol {Open Connection Editor} in the context menu
in \uicontrol {Connections}.
\image qtquick-connection-editor-assignment.png
\li Select \uicontrol Assignment as the type of the connections
component.
\li Select the target component for the property assignment.
\li Select the property of the target component to assign a value to.
\li Select the source component for the property assignment.
\li Select the property of the source component to fetch the value from.
\endlist
For an example of connecting the \c clicked signal of a button to a
\l{Adding States}{state}, see \l {Log In UI - Part 3}.
\endif
*/

View File

@@ -1,6 +1,6 @@
/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
@@ -30,43 +30,36 @@
\title Adding Connections
The user interface components and the application need to communicate with
each other. For example, a button needs to know that the user has clicked
on it. The button may then change color to indicate its state or perform an
action. Further, the application needs to know whether the user is clicking
the button, because it may need to relay this clicking event to other
applications.
QML has a signal and handler mechanism, that enables components to respond
to application events. Events are represented by \e signals. When a signal
is emitted, the corresponding \e {signal handler} is invoked to respond to
the event by using scripts or other operations placed in the handler.
To access a signal outside of the object that emits it, you can use the
\l Connections type for connecting to signals of arbitrary objects. A
Connections object can receive any signal from its specified target.
A component's property can be assigned a static value which stays constant
until it is explicitly assigned a new value. However, to make the fullest
use of QML and its built-in support for dynamic object behaviors, most QML
types use property bindings. This means that you can specify relationships
between different object properties so that when a property's dependencies
change in value, the property's value is automatically updated accordingly.
Behind the scenes, the QML engine monitors the property's dependencies (that
is, the variables in the binding expression). When a change is detected, the
QML engine re-evaluates the binding expression and applies the new result to
the property.
The following sections describe how to use the \uicontrol {Connections} view
to perform the following tasks:
\list
\li \l{Connecting Objects to Signals}
\li \l{Specifying Dynamic Properties}
\li \l{Connecting Components to Signals}
A signal and handler mechanism enables components to respond to
application events, which are represented by \e signals. When a
signal is emitted, the corresponding \e {signal handler} is
invoked to respond to the event by applying an action, for
example.
\li \l{Adding Bindings Between Properties}
A component's property can be assigned a static value that stays
constant until it is explicitly changed. To make the UI more
dynamic, you can use \e {property bindings}. This means that you
can specify relationships between component properties so that when
the value of a property changes, the values of any properties that
are bound to it are automatically updated accordingly.
\li \l{Specifying Dynamic Properties}
Each preset component has a set of preset properties that you
can specify values for. You can add custom properties that would
not otherwise exist for a particular \l{Component Types}
{component type} or your custom components.
\if defined(qtcreator)
\li \l{Managing C++ Backend Objects}
Application developers can access QObject objects implemented in C++
from QML files.
\endif
\endlist

View File

@@ -0,0 +1,96 @@
/****************************************************************************
**
** Copyright (C) 2021 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.
**
****************************************************************************/
/*!
\page qtquick-connection-view.html
\previouspage qtquick-properties-view.html
\nextpage qtquick-states-view.html
\title Connection View
The \uicontrol {Connection View} is a collection of views that enable you
to create connections between components and the application, to bind
component properties together, and to add custom properties for components.
\image qmldesigner-connections.png "Connections View"
The \l{glossary-component}{components} of the application UI and the
application logic need to communicate with each other. For example, a
button needs to know that the user has clicked it. The button may then
change color to indicate its state or perform an action. Further, the
application needs to know whether the user clicked the button because
it may need to relay this clicking event to other applications. For
this purpose, a button typically contains a \l{Mouse Area} component,
which can receive different pointer events and emit \e signals in
response to them.
Another way to connect components is to bind their \l{Properties}
{properties} together. A component's property can be assigned a static
value which stays constant until it is explicitly changed. To make the
UI more dynamic, you can use \e {property bindings}. This means that
you can specify relationships between component properties so that when
the value of a property changes, the values of any properties that are
bound to it are updated accordingly.
Each preset component has a set of \l{Specifying Component Properties}
{preset properties} that you can specify values for. You can add
custom properties that would not otherwise exist for a particular
\l{Component Types}{component type}.
\if defined(qtcreator)
In addition, application developers can use the \uicontrol Backends view
to access QObject objects implemented in C++ from QML files.
\endif
\section1 Summary of Connection Views
\table
\header
\li View
\li Purpose
\li Read More
\row
\li \uicontrol Connections
\li Create connections between components and the application logic
by accessing signals outside of the components that emit them.
\li \l{Connecting Components to Signals}
\row
\li \uicontrol Bindings
\li Dynamically change the behavior of a component by creating a
binding between the properties of two components.
\li \l{Adding Bindings Between Properties}
\row
\li \uicontrol Properties
\li Add custom properties that would not otherwise exist for a
particular preset component or your own custom component.
\li \l{Specifying Dynamic Properties}
\if defined(qtcreator)
\row
\li \uicontrol Backends
\li Access QObject objects implemented in C++ from QML files.
\li \l{Managing C++ Backend Objects}
\endif
\endtable
*/

View File

@@ -89,9 +89,9 @@
\li Enables you to modify the properties of the selected component.
\li \l {Specifying Component Properties}
\row
\li \l{Adding Connections}{Connection View}
\li \l{Connection View}
\li Enables you to add functionality to the UI by creating
connections between objects, signals, and object properties.
connections between components, signals, and component properties.
\li \l{Adding Connections}
\row
\li \l{Adding States}{States}

View File

@@ -26,7 +26,7 @@
/*!
\page qtquick-navigator.html
\previouspage quick-library.html
\nextpage qtquick-properties.html
\nextpage qtquick-properties-view.html
\title Navigator

View File

@@ -186,7 +186,7 @@
is clicked within the area.
You will now use the \uicontrol Connections view to
\l{Connecting Objects to Signals}{connect} the clicked signal of
\l{Connecting Components to Signals}{connect} the clicked signal of
\e registerButton to \e registerState and that of \e backButton
to \e loginState:

View File

@@ -205,8 +205,8 @@
The side menu is fully visible and accepts input only in the \e open state.
For more information about connecting objects to signals, see
\l {Connecting Objects to Signals}.
For more information about Connecting Components to Signals, see
\l {Connecting Components to Signals}.
\section1 Applying Effects

View File

@@ -46,7 +46,7 @@
\endlist
Users select buttons to navigate between the screens.
We use \l{Connecting Objects to Signals}{connections} to determine which
We use \l{Connecting Components to Signals}{connections} to determine which
screen to open when users select a particular button and \l{Adding States}
{States} to show the screens. We use the \l{Creating Animations}{timeline}
to create progress indicators for buttons and the \e Running screen.
@@ -234,7 +234,7 @@
We create similar connections between button objects and signals in the
other screens to apply other actions that move users to other screens.
For more information, see \l {Connecting Objects to Signals}.
For more information, see \l {Connecting Components to Signals}.
\section1 Showing the Current Time

View File

@@ -62,6 +62,7 @@
\li \l{Library}
\li \l{Navigator}
\li \l{Properties}
\li \l{Connection View}
\li \l{Transition Editor}
\li \l{Timeline}
\li \l{Curve Editor}
@@ -117,9 +118,9 @@
\endlist
\li \l{Adding Connections}
\list
\li\l{Connecting Objects to Signals}
\li\l{Specifying Dynamic Properties}
\li\l{Connecting Components to Signals}
\li\l{Adding Bindings Between Properties}
\li\l{Specifying Dynamic Properties}
\endlist
\li \l{Adding States}
\endlist