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

Doc: Add information about connections

Browse Source 
Divide the subtopics into individual topics.

Change-Id: If32ada04e9f305cf9a2e3a03072026eac92d005a
Reviewed-by: Thomas Hartmann <thomas.hartmann@qt.io>
This commit is contained in:
Leena Miettinen
2018-07-03 11:39:35 +02:00
committed by Thomas Hartmann
parent aeb192a814
commit 69108b614a
6 changed files with 309 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -90,6 +90,12 @@
\li \l {Editing QML Files in Design Mode}
\li \l {Editing PathView Properties}
\li \l {Adding Connections}
\list
\li \l{Connecting Objects to Signals}
\li \l{Specifying Dynamic Properties}
\li \l{Adding Bindings Between Properties}
\li \l{Managing C++ Backend Objects}
\endlist
\li \l {Creating Components}
\li \l {Creating Buttons}
\li \l {Creating Scalable Buttons and Borders}

74
doc/src/qtquick/qtquick-connection-editor-backend.qdoc Normal file
View File

@@ -0,0 +1,74 @@
/****************************************************************************
**
** Copyright (C) 2018 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.
**
****************************************************************************/
/*!
\contentspage {Qt Creator Manual}
\previouspage quick-property-bindings.html
\page quick-connections-backend.html
\nextpage quick-components.html
\title Managing C++ Backend Objects
Many applications provide QObject objects implemented in C++ that work as a
bridge between QML and C++. Such objects are typically registered with
\c qmlRegisterType or \c qmlRegisterSingletonType and then used by QML to
communicate with the C++ backend. Another example of such objects are the
state machines created by the \l {Using the Qt SCXML Compiler (qscxmlc)}
{Qt SCXML Compiler}.
Backend objects in a QML file are accessible if the QML file contains the
required imports. In addition, for a non-singleton QObject, a dynamic
property that contains the QObject must be specified.
A \e local QObject is instantiated in the current \e .qml file, as follows:
\badcode
property MyType myType: MyType {}.
\endcode
Otherwise the property is just defined, as follows:
\badcode
property MyType myType
\endcode
To manage backend objects:
\list 1
\li In the \uicontrol {Connections} view, select the
\uicontrol Backends tab to view accessible backend objects.
\image qmldesigner-backends.png
\li Select the \inlineimage plus.png
(\uicontrol Add) button to add a backend object in the
\uicontrol {Add New C++ Backend} dialog.
\li In the \uicontrol Type field, select the type of the backend QObject
to add.
\li Select the \uicontrol {Define object locally} check box if the
QObject is not registered as a singleton.
\li Select \uicontrol OK to add the required import and to create the
property for a non-singleton object.
\endlist
*/

65
doc/src/qtquick/qtquick-connection-editor-bindings.qdoc Normal file
View File

@@ -0,0 +1,65 @@
/****************************************************************************
**
** Copyright (C) 2018 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.
**
****************************************************************************/
/*!
\contentspage {Qt Creator Manual}
\previouspage quick-dynamic-properties.html
\page quick-property-bindings.html
\nextpage quick-connections-backend.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
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.
\image qmldesigner-bindings.png
To bind a property of an object to the property of another object:
\list 1
\li In the \uicontrol {Connections} view, select the
\uicontrol {Bindings} tab.
\li Select the \inlineimage plus.png
(\uicontrol Add) button to add a binding.
\li Select \uicontrol Item to select the target object whose property
you want to change dynamically.
\li Select \uicontrol Property to select the property to bind to a
source property.
\li Select \uicontrol {Source Item} to select the object whose property
you want to use to determine the behavior of the target object.
\li Select \uicontrol {Source Property} to select the property to bind
the target property to.
\endlist
*/

58
doc/src/qtquick/qtquick-connection-editor-properties.qdoc Normal file
View File

@@ -0,0 +1,58 @@
/****************************************************************************
**
** Copyright (C) 2018 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.
**
****************************************************************************/
/*!
\contentspage {Qt Creator Manual}
\previouspage qmldesigner-connections.html
\page quick-dynamic-properties.html
\nextpage quick-property-bindings.html
\title Specifying Dynamic Properties
You can bind object 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.
You can specify dynamic properties for objects in the
\uicontrol Connections view.
\image qmldesigner-dynamicprops.png
To specify dynamic properties for an object:
\list 1
\li In the \uicontrol {Connections} view, select the
\uicontrol {Properties} tab.
\li Select \uicontrol Item to select the object to specify the property
for.
\li Select \uicontrol Property to give a name to the property.
\li Select \uicontrol {Property Type} to specify the type of the
property.
\li Select \uicontrol {Property Value} to specify the value of the
property.
\endlist
*/

71
doc/src/qtquick/qtquick-connection-editor-signals.qdoc Normal file
View File

@@ -0,0 +1,71 @@
/****************************************************************************
**
** 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.
**
****************************************************************************/
/*!
\contentspage {Qt Creator Manual}
\previouspage qmldesigner-connections.html
\page quick-signals.html
\nextpage quick-dynamic-properties.html
\title Connecting Objects to Signals
To receive a notification when a particular signal is emitted for a
particular object, the object 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 MouseArea type from the \l QtQuick
module 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.
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.
\image qmldesigner-connections.png
To connect objects to signals:
\list 1
\li In the \uicontrol {Connections} view, select the
\uicontrol {Connections} tab.
\li Select the \inlineimage plus.png
(\uicontrol Add) button to add a connection.
\li Select \uicontrol Target to add the object to connect to a signal.
\li Select \uicontrol {Signal Handler} to select the signal that the
connection will listen to from a list of all signals available for
the object.
\li Select \uicontrol Actions to specify the action to perform when
the signal is emitted. You use JavaScript to specify the actions.
\endlist
*/

178
doc/src/qtquick/qtquick-connection-editor.qdoc
View File

@@ -27,153 +27,45 @@
\contentspage {Qt Creator Manual}
\previouspage qmldesigner-pathview-editor.html
\page qmldesigner-connections.html
\nextpage quick-components.html
\nextpage quick-signals.html
\title Adding Connections
You can use the \uicontrol {Connections} view to:
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 sependencies
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 Connect objects to signals.
\li Specify dynamic properties for objects.
\li Create bindings between the properties of two objects.
\li Manage backend QObjects.
\li \l{Connecting Objects to Signals}
\li \l{Specifying Dynamic Properties}
\li \l{Adding Bindings Between Properties}
\li \l{Managing C++ Backend Objects}
\endlist
For examples of adding connections, see
\l{Creating Scalable Buttons and Borders}.
\section1 Connecting Objects to Signals
To connect objects to signals in QML, create \l{Connections} objects.
\image qmldesigner-connections.png
To create the connections:
\list 1
\li Select the \uicontrol {Connections} tab.
\li Select the \inlineimage plus.png
(\uicontrol Add) button to add a connection.
\li Select \uicontrol Target to add the object to connect to a signal.
\li Select \uicontrol {Signal Handler} to select the signal that the connection
will listen to from a list of all signals available for the object.
\li Select \uicontrol Actions to specify the action to perform when
the signal is emitted. You use JavaScript to specify the actions.
\endlist
\section1 Specifying Dynamic Properties
You can bind \l{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.
\image qmldesigner-dynamicprops.png
To specify dynamic properties for an object:
\list 1
\li Select the \uicontrol {Properties} tab.
\li Select \uicontrol Item to select the object to specify the property for.
\li Select \uicontrol Property to give a name to the property.
\li Select \uicontrol {Property Type} to specify the type of the property.
\li Select \uicontrol {Property Value} to specify the value of the property.
\endlist
\section1 Adding Bindings Between Properties
To dynamically change the behavior of an object, you can create a
\l{Property Binding} between the properties of two objects.
\image qmldesigner-bindings.png
To bind a property of an object to the property of another object:
\list 1
\li Select the \uicontrol {Bindings} tab.
\li Select the \inlineimage plus.png
(\uicontrol Add) button to add a binding.
\li Select \uicontrol Item to select the target object whose property you want
to change dynamically.
\li Select \uicontrol Property to select the property to bind to a source
property.
\li Select \uicontrol {Source Item} to select the object whose property you
want to use to determine the behavior of the target object.
\li Select \uicontrol {Source Property} to select the property to bind the
target property to.
\endlist
\section1 Managing C++ Backend Objects
Many applications provide QObject objects implemented in C++ that work as a
bridge between QML and C++. Such objects are typically registered with
qmlRegisterType or qmlRegisterSingletonType and then used by QML to
communicate with the C++ backend. Another example of such objects are the
state machines created by the \l {Using the Qt SCXML Compiler (qscxmlc)}
{Qt SCXML Compiler}.
Backend objects in a QML file are accessible if the QML file contains the
required imports. In addition, for a non-singleton QObject, a dynamic
property that contains the QObject must be specified.
A \e local QObject is instantiated in the current \e .qml file, as follows:
\badcode
property MyType myType: MyType {}.
\endcode
Otherwise the property is just defined, as follows:
\badcode
property MyType myType
\endcode
To manage backend objects:
\list 1
\li Select the \uicontrol Backends tab to view accessible backend
objects.
\image qmldesigner-backends.png
\li Select the \inlineimage plus.png
(\uicontrol Add) button to add a backend object in the
\uicontrol {Add New C++ Backend} dialog.
\li In the \uicontrol Type field, select the type of the backend QObject
to add.
\li Select the \uicontrol {Define object locally} check box if the
QObject is not registered as a singleton.
\li Select \uicontrol OK to add the required import and to create the
property for a non-singleton object.
\endlist
*/