doc: more ApplicationManagerWindow documentation

Change-Id: I6751f45711d71681e9dff57f51b26ff5f97e8ad4
Pick-to: 6.7
Reviewed-by: Dominik Holland <dominik.holland@qt.io>

2 files changed, 29 insertions, 46 deletions

diff --git a/doc/singlevsmultiprocess.qdoc b/doc/singlevsmultiprocess.qdoc
index 0aa0fe31..def1a228 100644
--- a/doc/singlevsmultiprocess.qdoc
+++ b/doc/singlevsmultiprocess.qdoc
@@ -136,11 +136,7 @@ multi-process mode. Windows are exposed from the application to the System UI th
 multi-process mode for your application, you have to use an \l{ApplicationManagerWindow}. There
 are also other benefits to using an ApplicationManagerWindow, such as window properties.
 
-In multi-process mode an ApplicationManagerWindow derives from Window; unlike in single-process
-mode which derives from QtObject. As a result, several properties coming from Window won't have any
-effect in single-process mode, although ApplicationManagerWindow still defines them for
-compatibility. The following are some examples:
-
+Some noteworthy differences between application windows in single- and multi-process mode are:
 \list
 \li An ApplicationManagerWindow is exposed to the System UI in two different ways.
     \list
@@ -152,12 +148,14 @@ compatibility. The following are some examples:
            Items from System UI itself or from any other running application as they are all
            sharing the same QML scene.
     \endlist
-\li Many properties, functions, and signals defined in a Window are not yet re-implemented in the
-    single-process version of ApplicationManagerWindow (amongst others the \c opacity property).
-\li The \c color property needs to be provided with pre-multiplied alpha in multi-process and with
-    straight alpha in single-process mode.
-\li In multi-process mode, when an ApplicationManagerWindow is clicked or touched, it will take
-    the focus, whereas in single-process mode the focus doesn't change.
+\li Some properties, functions, and signals defined in a window will behave differently depending on
+    on the run mode: most importantly the lack of window states (like maximized or fullscreen) in
+    single-process mode. Please refer to the documentation of ApplicationManagerWindow for more
+    details.
+\li Focus handling does work the same in both modes, but you have to be aware that in single-process
+    mode, the focus item is shared between the System UI and the active application.
+    Pre 6.7 the focus didn't change when clicking/tapping into an otherwise passive area of an
+    application window in single-process mode.
 \li An error encountered in a code block due to properties or methods described above will cause
     subsequent statements not to be evaluated in multi-process mode; but this is not the case in
     single-process mode.
diff --git a/src/shared-main-lib/applicationmanagerwindow.cpp b/src/shared-main-lib/applicationmanagerwindow.cpp
index 1d37abeb..e5dbb233 100644
--- a/src/shared-main-lib/applicationmanagerwindow.cpp
+++ b/src/shared-main-lib/applicationmanagerwindow.cpp
@@ -17,12 +17,25 @@ QT_BEGIN_NAMESPACE_AM
 
     This QML item can be used as the root item in your QML application. In doing so, you enable
     your application to be usable in both single-process (EGL fullscreen, desktop) and
-    multi-process (Wayland) mode. It inherits from \l Window in multi-process and from \l QtObject
-    in single-process mode. In contrast to a \l Window it is visible by default. This documentation
-    reflects the Window inheritance. Note that only a subset of the Window type members have been
-    added to ApplicationManagerWindow when derived from QtObject. Additional details can be found
-    in the section about \l {The Root Element}{the root element} and \l {Application Windows}
-    {application windows}.
+    multi-process (Wayland) mode. In order to achieve this, this class is not derived from
+    QQuickWindow directly, but from QObject.
+
+    The API closely resembles that of \l Window, but there are some things missing, which are
+    either not applicable for the embedded use case or cannot be supported in the single-process
+    case. If you need access to those, you still can via the \l backingObject property. Check the
+    the \l singleProcess property to see if you are in single-process mode and if the actual
+    backingObject is an \l Item or a \l Window.
+
+    In contrast to a \l Window, an ApplicationManagerWindow is visible by default.
+
+    Additional details can be found in the section about \l {The Root Element}{the root element}
+    and \l {Application Windows}{application windows}.
+
+    \note Before version 6.7, this class inherited from \l Window in multi-process and from \l
+          QtObject in single-process mode, but that made it impossible to use qml tooling on this
+          class. There are no "revision" markers in the QML API and no "since" markers in the
+          documentation after re-implementing this class, as it would be ambiguous which of the two
+          old implementations they refer to.
 
     The QML import for this item is
 
@@ -40,34 +53,6 @@ QT_BEGIN_NAMESPACE_AM
         }
     }
     \endqml
-
-    In order to make your applications easily runnable outside of the application manager, even
-    though you are using an ApplicationManagerWindow as a root item, you can simply provide this
-    little dummy import to your application.
-
-    \list 1
-    \li Pick a base dir and create a \c{QtApplicationManager.Application} directory in it
-    \li Add a file named \c qmldir there, consisting of the single line
-        \c{ApplicationManagerWindow 2.0 ApplicationManagerWindow.qml}
-    \li Add a second file named \c ApplicationManagerWindow.qml, with the following content
-
-    \qml
-    import QtQuick
-
-    Window {
-        signal windowPropertyChanged
-        function setWindowProperty(name, value) {}
-        // ... add additional dummy members that are used by your implementation
-
-        width: 1280   // use your screen width here
-        height: 600   // use your screen height here
-        visible: true
-    }
-    \endqml
-
-    \endlist
-
-    Now you can run your application for instance with: \c{qml -I <path to base dir>}
 */
 
 
@@ -272,7 +257,7 @@ void ApplicationManagerWindow::hide()
 
     Equivalent to setting \l visible to \c true.
 
-    \sa hide()
+    \sa hide(), visibility
 */
 void ApplicationManagerWindow::show()
 {