Doc: Add information about connections

Divide the subtopics into individual topics.

Change-Id: If32ada04e9f305cf9a2e3a03072026eac92d005a
Reviewed-by: Thomas Hartmann <thomas.hartmann@qt.io>

5 files changed, 303 insertions, 143 deletions

diff --git a/doc/src/qtquick/qtquick-connection-editor-backend.qdoc b/doc/src/qtquick/qtquick-connection-editor-backend.qdoc
new file mode 100644
index 0000000000..e79b32eec2
--- /dev/null
+++ b/doc/src/qtquick/qtquick-connection-editor-backend.qdoc
@@ -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
+*/
diff --git a/doc/src/qtquick/qtquick-connection-editor-bindings.qdoc b/doc/src/qtquick/qtquick-connection-editor-bindings.qdoc
new file mode 100644
index 0000000000..614a3841ea
--- /dev/null
+++ b/doc/src/qtquick/qtquick-connection-editor-bindings.qdoc
@@ -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
+*/
diff --git a/doc/src/qtquick/qtquick-connection-editor-properties.qdoc b/doc/src/qtquick/qtquick-connection-editor-properties.qdoc
new file mode 100644
index 0000000000..2288128327
--- /dev/null
+++ b/doc/src/qtquick/qtquick-connection-editor-properties.qdoc
@@ -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
+
+*/
diff --git a/doc/src/qtquick/qtquick-connection-editor-signals.qdoc b/doc/src/qtquick/qtquick-connection-editor-signals.qdoc
new file mode 100644
index 0000000000..010ab17847
--- /dev/null
+++ b/doc/src/qtquick/qtquick-connection-editor-signals.qdoc
@@ -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
+*/
diff --git a/doc/src/qtquick/qtquick-connection-editor.qdoc b/doc/src/qtquick/qtquick-connection-editor.qdoc
index 92062021cf..aa25551bf9 100644
--- a/doc/src/qtquick/qtquick-connection-editor.qdoc
+++ b/doc/src/qtquick/qtquick-connection-editor.qdoc
@@ -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
-
 */