Add overview documentation for Qt Quick Layouts

Change-Id: I79df2abca1de42496f75fc08a779203a406ce155
Reviewed-by: Nico Vertriest <nico.vertriest@digia.com>
Reviewed-by: Jens Bache-Wiig <jens.bache-wiig@digia.com>

5 files changed, 229 insertions, 0 deletions

diff --git a/src/layouts/doc/images/rowlayout-minimum.png b/src/layouts/doc/images/rowlayout-minimum.png
new file mode 100644
index 00000000..5875325c
--- /dev/null
+++ b/src/layouts/doc/images/rowlayout-minimum.png
diff --git a/src/layouts/doc/qtquicklayouts.qdocconf b/src/layouts/doc/qtquicklayouts.qdocconf
index ad33416f..a13066b8 100644
--- a/src/layouts/doc/qtquicklayouts.qdocconf
+++ b/src/layouts/doc/qtquicklayouts.qdocconf
@@ -26,6 +26,8 @@ qhp.QtQuickLayouts.subprojects.qtquicklayoutsqmltypes.type = manual
 
 depends = qtqml qtquick qtwidgets qtdoc qtquickcontrols
 
+exampledirs += src/snippets
+
 headerdirs += ..
 
 sourcedirs += ..
diff --git a/src/layouts/doc/src/qtquicklayouts-index.qdoc b/src/layouts/doc/src/qtquicklayouts-index.qdoc
index c2280f5d..fb9c3898 100644
--- a/src/layouts/doc/src/qtquicklayouts-index.qdoc
+++ b/src/layouts/doc/src/qtquicklayouts-index.qdoc
@@ -52,6 +52,16 @@
 
     \section1 Related information
 
+    \section2 Guides
+     \list
+      \li \l{Qt Quick Layouts Overview}
+     \endlist
+
+    \section2 Examples
+     \list
+      \li \l{Qt Quick Controls - Basic Layouts Example}
+     \endlist
+
     \section2 Reference
      \list
       \li \l{Qt Quick Layouts QML Types}{Qt Quick Layouts QML Types}
diff --git a/src/layouts/doc/src/qtquicklayouts-overview.qdoc b/src/layouts/doc/src/qtquicklayouts-overview.qdoc
new file mode 100644
index 00000000..b7302dad
--- /dev/null
+++ b/src/layouts/doc/src/qtquicklayouts-overview.qdoc
@@ -0,0 +1,128 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qtquicklayouts-overview.html
+    \title Qt Quick Layouts Overview
+    \brief A set of APIs for arranging QML items in a user interface.
+
+    Qt Quick Layouts are items that are used to arrange items in a user interface. Since Qt Quick
+    Layouts also resize their items, they are well suited for resizable user interfaces.
+
+
+    \section1 Key Features
+
+
+    Some of the key features are:
+
+    \list
+        \li \l{Layout::alignment}{Alignment} of items can be specified with the
+            \l{Layout::alignment}{Layout.alignment} property
+        \li \l{Layout::fillWidth}{Resizable items} can be specified with the
+            \l{Layout::fillWidth}{Layout.fillWidth} and \l{Layout::fillHeight}{Layout.fillHeight}
+            properties.
+        \li \l{Size constraints} can be specified with
+            \l{Layout::minimumWidth}{Layout.minimumWidth},
+            \l{Layout::preferredWidth}{Layout.preferredWidth}, and
+            \l{Layout::maximumWidth}{Layout.maximumWidth}  properties ("Width" can be replaced
+            with "Height" for specifying similar constraints to the height).
+        \li \l{RowLayout::spacing}{Spacings} can be specified with \l{RowLayout::spacing}{spacing},
+            \l{GridLayout::rowSpacing}{rowSpacing} or \l{GridLayout::columnSpacing}{columnSpacing}
+    \endlist
+
+    In addition to the above features, GridLayout adds these features:
+    \list
+        \li \l{Layout::row}{Grid coordinates} can be specified with the \l{Layout::row}{Layout.row} and
+            \l{Layout::column}{Layout.column}.
+        \li \l{GridLayout::flow}{Automatic grid coordinates} used together with the
+            \l{GridLayout::flow}{flow}, \l{GridLayout::rows}{rows}, and
+            \l{GridLayout::columns}{columns} properties.
+        \li \l{Layout::columnSpan}{Spans} across rows or columns can be specified with the
+            \l{Layout::rowSpan}{Layout.rowSpan} and \l{Layout::columnSpan}{Layout.columnSpan}
+            properties.
+    \endlist
+
+
+
+    \section1 Size Constraints
+    Since an item can be resized by its layout, the layout needs to know the
+    \l{Layout::minimumWidth}{minimum}, \l{Layout::preferredWidth}{preferred},
+    and \l{Layout::maximumWidth}{maximum} sizes of all items where \l{Layout::fillWidth}{Layout.fillWidth} or
+    \l{Layout::fillHeight}{Layout.fillHeight} is set to \c true.
+    For instance, the following will produce a layout with two rectangles lying side-by-side that
+    stretches horizontally. The azure rectangle can be resized from 50x150 to 300x150, and the plum
+    rectangle can be resized from 100x100 to ∞x100.
+
+    \snippet windowconstraints.qml rowlayout
+
+    \image rowlayout-minimum.png "RowLayout at its minimum"
+
+    Combining each item's constraints will give these implicit constraints to the layout element:
+
+    \table
+    \header
+        \li
+        \li minimum
+        \li preferred
+        \li maximum
+    \row
+        \li implicit constraints (width)
+        \li 156
+        \li 306
+        \li ∞ (\c Number.POSITIVE_INFINITY)
+    \row
+        \li implicit constraints (heights)
+        \li 150
+        \li 150
+        \li 150
+    \endtable
+
+    Thus, the layout cannot be narrower than 156 or be taller or shorter than 150 without breaking
+    any of the constraints of its child items.
+
+    \section1 Connecting windows and layouts
+    You can just use normal anchoring concepts to ensure that the layout will follow the window
+    resizing.
+
+    \snippet windowconstraints.qml anchoring
+
+    The size constraints of layouts can be used to ensure that the window cannot be resized beyond
+    the layout constraints. You can take the size constraints from the layout and set these
+    constraints on the minimumWidth, minimumHeight, maximumWidth, and maximumHeight of the Window
+    element. The following code ensures that the window cannot be resized beyond the constraints of
+    the layout:
+
+    \snippet windowconstraints.qml bindconstraints
+
+    \note Since layout.Layout.maximumWidth is infinite in this case, we cannot bind that to the
+    maximumWidth property of Window, since that is an integer number. We therefore set a fixed
+    maximum width to 1000.
+
+    Finally, you usually want the initial size of the window to be the layout's implicit size:
+
+    \snippet windowconstraints.qml binddefaultsize
+*/
diff --git a/src/layouts/doc/src/snippets/windowconstraints.qml b/src/layouts/doc/src/snippets/windowconstraints.qml
new file mode 100644
index 00000000..673169a3
--- /dev/null
+++ b/src/layouts/doc/src/snippets/windowconstraints.qml
@@ -0,0 +1,89 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.0
+import QtQuick.Controls 1.0
+import QtQuick.Layouts 1.0
+
+ApplicationWindow {
+    //! [binddefaultsize]
+    width: layout.implicitWidth
+    height: layout.implicitHeight
+    //! [binddefaultsize]
+    //! [bindconstraints]
+    minimumWidth: layout.Layout.minimumWidth
+    minimumHeight: layout.Layout.minimumHeight
+    maximumWidth: 1000
+    maximumHeight: layout.Layout.maximumHeight
+    //! [bindconstraints]
+
+    //! [rowlayout]
+    //! [anchoring]
+    RowLayout {
+        id: layout
+        anchors.fill: parent
+    //! [anchoring]
+        spacing: 6
+        Rectangle {
+            color: 'azure'
+            Layout.fillWidth: true
+            Layout.minimumWidth: 50
+            Layout.preferredWidth: 100
+            Layout.maximumWidth: 300
+            Layout.minimumHeight: 150
+            Text {
+                anchors.centerIn: parent
+                text: parent.width + 'x' + parent.height
+            }
+        }
+        Rectangle {
+            color: 'plum'
+            Layout.fillWidth: true
+            Layout.minimumWidth: 100
+            Layout.preferredWidth: 200
+            Layout.preferredHeight: 100
+            Text {
+                anchors.centerIn: parent
+                text: parent.width + 'x' + parent.height
+            }
+        }
+    }
+    //! [rowlayout]
+}