diff options
| author | Venugopal Shivashankar <Venugopal.Shivashankar@qt.io> | 2017-10-18 12:59:36 +0200 |
|---|---|---|
| committer | Shawn Rutledge <shawn.rutledge@qt.io> | 2017-11-03 09:36:44 +0000 |
| commit | c143c790b7a6fceaac16492023090940c81acc42 (patch) | |
| tree | db8c1164153e6ecb0dc59ba1a36787043ee37f2e | |
| parent | ee00fa01dc41deaaedfa0d1d5cc6cd750bfe75f4 (diff) | |
Doc: Move the warning about manipulating QML objects from C++
Manipulating QML objects from C++ is not a best practice when
integrating QML and C++, except for testing and prototying. So its apt
to warn the reader about such an approach much earlier.
Task-number: QTPM-425
Change-Id: Iebb93d099008ff3ebcefe6af25364afe379b7fcf
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
| -rw-r--r-- | src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc | 12 | ||||
| -rw-r--r-- | src/qml/doc/src/cppintegration/topic.qdoc | 2 | ||||
| -rw-r--r-- | src/qml/doc/src/cppintegration/warning.qdocinc | 6 |
3 files changed, 9 insertions, 11 deletions
diff --git a/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc b/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc index 4dc32e3588..7c2ff703c6 100644 --- a/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc +++ b/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc @@ -114,17 +114,7 @@ multiple children with the same \c objectName. In this case, QObject::findChildren() can be used to find all children with a matching \c objectName. -\warning While it is possible to use C++ to access and manipulate QML objects -deep into the object tree, we recommend that you do not take this approach -outside of application testing and prototyping. One strength of QML and C++ -integration is the ability to implement the QML user interface separately -from the C++ logic and dataset backend, and this strategy breaks if the C++ -side reaches deep into the QML components to manipulate them directly. This -would make it difficult to, for example, swap a QML view component for -another view, if the new component was missing a required \c objectName. It -is better for the C++ implementation to know as little as possible about the -QML user interface implementation and the composition of the QML object tree. - +\include warning.qdocinc \section1 Accessing Members of a QML Object Type from C++ diff --git a/src/qml/doc/src/cppintegration/topic.qdoc b/src/qml/doc/src/cppintegration/topic.qdoc index da06c195dc..6b6e308edf 100644 --- a/src/qml/doc/src/cppintegration/topic.qdoc +++ b/src/qml/doc/src/cppintegration/topic.qdoc @@ -190,6 +190,8 @@ invoke their methods and receive their signal notifications. This is possible du all QML object types are implemented using QObject-derived classes, enabling the QML engine to dynamically load and introspect objects through the Qt meta object system. +\include warning.qdocinc + For more information on accessing QML objects from C++, see the documentation on \l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++}. diff --git a/src/qml/doc/src/cppintegration/warning.qdocinc b/src/qml/doc/src/cppintegration/warning.qdocinc new file mode 100644 index 0000000000..a5da22b2a7 --- /dev/null +++ b/src/qml/doc/src/cppintegration/warning.qdocinc @@ -0,0 +1,6 @@ +\warning Although it is possible to access QML objects from C++ and manipulate +them, it is not the recommended approach, except for testing and prototyping +purposes. One of the strengths of QML and C++ integration is the ability to +implement UIs in QML separate from the C++ logic and dataset backend, and this +fails if the C++ side starts manipulating QML directly. Such an approach also +makes changing the QML UI difficult without affecting its C++ counterpart. |