From cd425eb9b6674da0f3e920dc9829cb20ebe2ca95 Mon Sep 17 00:00:00 2001
From: Mitch Curtis <mitch.curtis@qt.io>
Date: Tue, 4 Oct 2016 15:31:44 +0200
Subject: Fix some of the ApplicationWindow documentation review findings

Change-Id: Ifa4ae65923f3073ced1c46dd56725e00b34a689d
Task-number: QTBUG-55904
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>
---
 .../doc/src/qtquickcontrols2-customize.qdoc        | 32 ++++++++++++++++++++++
 src/quicktemplates2/qquickapplicationwindow.cpp    | 32 +++++++++++++++++++++-
 2 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
index f37519de..71ffe350 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
@@ -335,6 +335,38 @@
     \l {Customizing a Control} section. The code can be used as a starting
     point to implement a custom look and feel.
 
+    \section2 Customizing ApplicationWindow
+
+        ApplicationWindow consists of one visual item:
+        \l {ApplicationWindow::background}{background}. It is also possible
+        to customize the \l {ApplicationWindow::overlay}{modal} and
+        \l {ApplicationWindow::overlay}{modeless} items.
+
+        \code
+        import QtQuick 2.7
+        import QtQuick.Controls 2.0
+
+        ApplicationWindow {
+            visible: true
+
+            background: Rectangle {
+                gradient: Gradient {
+                    GradientStop { position: 0; color: "#ffffff" }
+                    GradientStop { position: 1; color: "#c1bbf9" }
+                }
+            }
+
+            overlay.modal: Rectangle {
+                color: "#8f28282a"
+            }
+
+            overlay.modeless: Rectangle {
+                color: "#2f28282a"
+            }
+        }
+        \endcode
+
+
     \section2 Customizing BusyIndicator
 
         BusyIndicator consists of two visual items: \l {Control::background}{background}
diff --git a/src/quicktemplates2/qquickapplicationwindow.cpp b/src/quicktemplates2/qquickapplicationwindow.cpp
index 67fcd78b..d03633a3 100644
--- a/src/quicktemplates2/qquickapplicationwindow.cpp
+++ b/src/quicktemplates2/qquickapplicationwindow.cpp
@@ -93,7 +93,7 @@ QT_BEGIN_NAMESPACE
 
     \note By default, an ApplicationWindow is not visible.
 
-    \sa Page, {Container Controls}
+    \sa {Customizing ApplicationWindow}, Page, {Container Controls}
 */
 
 class QQuickApplicationWindowPrivate : public QQuickItemChangeListener
@@ -274,9 +274,15 @@ QQuickApplicationWindow::~QQuickApplicationWindow()
     The background item is stacked under the \l {contentItem}{content item},
     but above the \l {Window::color}{background color} of the window.
 
+    The background item is useful for images and gradients, for example,
+    but the \l {Window::}{color} property is preferable for solid colors,
+    as it doesn't need to create an item.
+
     \note If the background item has no explicit size specified, it automatically
           follows the control's size. In most cases, there is no need to specify
           width or height for a background item.
+
+    \sa {Customizing ApplicationWindow}, contentItem, header, footer, overlay
 */
 QQuickItem *QQuickApplicationWindow::background() const
 {
@@ -401,6 +407,17 @@ void QQuickApplicationWindow::setFooter(QQuickItem *footer)
     This default property holds the list of all objects declared as children of
     the window.
 
+    The data property allows you to freely mix visual children, resources and
+    other windows in an ApplicationWindow.
+
+    If you assign an Item to the contentData list, it becomes a child of the
+    window's contentItem, so that it appears inside the window. The item's
+    parent will be the window's \l contentItem.
+
+    It should not generally be necessary to refer to the contentData property,
+    as it is the default property for ApplicationWindow and thus all child
+    items are automatically assigned to this property.
+
     \sa contentItem
 */
 QQmlListProperty<QObject> QQuickApplicationWindow::contentData()
@@ -413,6 +430,11 @@ QQmlListProperty<QObject> QQuickApplicationWindow::contentData()
     \readonly
 
     This property holds the window content item.
+
+    The content item is stacked above the \l background item, and under the
+    \l header, \l footer, and \l overlay items.
+
+    \sa background, header, footer, overlay
 */
 QQuickItem *QQuickApplicationWindow::contentItem() const
 {
@@ -469,6 +491,14 @@ QQuickItem *QQuickApplicationWindow::activeFocusControl() const
         \li This property holds a component to use as a visual item that implements
             background dimming for modeless popups. It is created for and stacked below
             visible dimming popups.
+    \row
+        \li overlay.pressed()
+        \li This signal is emitted when the overlay is pressed by the user while
+            a popup is visible.
+    \row
+        \li overlay.released()
+        \li This signal is emitted when the overlay is released by the user while
+            a modal popup is visible.
     \endtable
 
     \sa Popup::modal, Popup::dim
-- 
cgit v1.2.3