Add documentation to QtQuick.Layouts

Change-Id: Ia220ccfd534ca089367c4ee954e081770784524c
Reviewed-by: Jens Bache-Wiig <jens.bache-wiig@digia.com>
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

src/controls/doc/qtquickcontrols.qdocconf

@@ -29,7 +29,7 @@ qhp.qtquickcontrols.subprojects.styleqmltypes.indexTitle = Qt Quick Controls Sty
 qhp.qtquickcontrols.subprojects.styleqmltypes.selectors = class fake:qmlclass
 qhp.qtquickcontrols.subprojects.styleqmltypes.sortPages = true
 
-depends = qtqml qtquick qtwidgets qtdoc
+depends = qtqml qtquick qtwidgets qtdoc qtquicklayouts
 
 exampledirs += ../../../examples/
 

src/controls/doc/src/qtquickcontrols-index.qdoc

@@ -59,6 +59,11 @@
     Controls are typically items that are used to present or receive input from the user.
     \annotatedlist controls
 
+    \section1 Layouts
+    \l{Qt Quick Layouts}{Layouts} can be used to have dynamic user interfaces where the UI
+    adapts to the available geometry.
+    \annotatedlist layouts
+
     \section1 Related information
 
     \section2 Guides

src/layouts/doc/qtquicklayouts-index.qdoc

+/****************************************************************************
+**
+** 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-index.html
+    \title Qt Quick Layouts
+
+    \brief The Qt Quick Layouts module is an add-on module of Qt.
+
+    \section1 Getting started
+
+    The QML types can be imported into your application using the following import statement in your \c {.qml} file.
+
+    \code
+     import QtQuick.Layouts 1.0
+    \endcode
+
+    \section1 Layouts
+    Layouts are items that are used to arrange items in the user interface. Layout are dynamic -
+    when the layout changes geometry it will typically incluence the arrangement of its child
+    items.
+    \annotatedlist layouts
+
+*/

src/layouts/doc/qtquicklayouts.qdocconf

+include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
+
+# Name of the project.
+project = QtQuickLayouts
+description = Qt Quick Layouts Documentation
+
+depends = qtqml qtquick qtwidgets qtdoc qtquickcontrols
+
+# Directories in which to search for files to document and images.
+# By default set to the root directory of the project for sources
+# and headers and qdoc will therefore generate output for each file.
+# Images should be placed in <rootdir>/dic/images and examples in
+# <rootdir>/examples.
+# Paths are relative to the  location of this file.
+
+exampledirs += ../../../examples/
+
+headerdirs += ../
+
+sourcedirs += ../
+
+imagedirs += images
+
+# The following parameters are for creating a qhp file, the qhelpgenerator
+# program can convert the qhp file into a qch file which can be opened in
+# Qt Assistant and/or Qt Creator.
+
+# Defines the name of the project. You cannot use operators (+, =, -) in
+# the name. Properties for this project are set using a qhp.<projectname>.property
+# format.
+qhp.projects = qtquicklayouts
+
+# Sets the name of the output qhp file.
+qhp.qtquicklayouts.file = qtquicklayouts.qhp
+
+# Namespace for the output file. This namespace is used to distinguish between
+# different documentation files in Creator/Assistant.
+qhp.qtquicklayouts.namespace = qtquicklayouts.100
+
+# Title for the package, will be the main title for the package in
+# Assistant/Creator.
+qhp.qtquicklayouts.indexTitle = Qt Quick Layouts
+
+# Extra files to add to the output which are not linked to from anywhere
+# using a qdoc \l command.
+#qhp.qtquicklayouts.extraFiles = style/qtquicklayouts.css
+
+# Only update the name of the project for the next variables.
+qhp.qtquicklayouts.virtualFolder  = qtquicklayouts
+
+qhp.qtquicklayouts.subprojects = qtquicklayoutsqmltypes
+qhp.qtquicklayouts.subprojects.qtquicklayoutsqmltypes.title = Qt Quick Layouts QML Types
+qhp.qtquicklayouts.subprojects.qtquicklayoutsqmltypes.indexTitle = Qt Quick Layouts QML Types
+qhp.qtquicklayouts.subprojects.qtquicklayoutsqmltypes.selectors = class fake:headerfile
+qhp.qtquicklayouts.subprojects.qtquicklayoutsqmltypes.sortPages = true

src/layouts/layouts.pro

@@ -5,7 +5,7 @@ IMPORT_VERSION = 2.1
 
 QT *= qml-private quick-private v8-private gui-private core-private
 
-#QMAKE_DOCS = $$PWD/doc/qtquicklayouts.qdocconf
+QMAKE_DOCS = $$PWD/doc/qtquicklayouts.qdocconf
 
 SOURCES += plugin.cpp \
     qlayoutpolicy.cpp \
@@ -21,6 +21,6 @@ HEADERS += \
     qquicklinearlayout_p.h
 
 OTHER_FILES += \
-$$PWD/plugin.json
+    $$PWD/plugin.json
 
 load(qml_plugin)

src/layouts/qquicklinearlayout.cpp

@@ -43,20 +43,105 @@
 #include <QtCore/qnumeric.h>
 #include "qdebug.h"
 #include <limits>
+
 /*!
     \qmltype RowLayout
     \instantiates QQuickRowLayout
-    \inqmlmodule QtDesktop 1.0
-    \brief RowLayout is doing bla...bla...
+    \inqmlmodule QtQuick.Layouts 1.0
+    \ingroup layouts
+    \brief RowLayout is the same as a \l GridLayout with just one row.
+
+    It is available as a convenience for developers, as it offers a cleaner API.
+
+    \sa ColumnLayout
+    \sa GridLayout
 */
 
 /*!
     \qmltype ColumnLayout
     \instantiates QQuickColumnLayout
-    \inqmlmodule QtDesktop 1.0
-    \brief ColumnLayout is doing bla...bla...
+    \inqmlmodule QtQuick.Layouts 1.0
+    \ingroup layouts
+    \brief ColumnLayout is the same as a \l GridLayout with just one column.
+
+    It is available as a convenience for developers, as it offers a cleaner API.
+
+    \sa RowLayout
+    \sa GridLayout
 */
 
+
+/*!
+    \qmltype GridLayout
+    \instantiates QQuickGridLayout
+    \inqmlmodule QtQuick.Layouts 1.0
+    \ingroup layouts
+    \brief Provides a way of dynamically arranging items in a grid.
+
+    If the GridLayout is resized, all items in the layout will be rearranged. It is similar
+    to the widget-based QGridLayout. All children of the GridLayout element will belong to
+    the layout. If you want a layout with just one row or one column, you can use the
+    \l RowLayout or \l ColumnLayout. These offers a bit more convenient API, and improves
+    readability.
+
+    By default items will be arranged according to the \l flow property. The default value of
+    the \l flow property is \c GridLayout.LeftToRight.
+
+    If the \l columns property is specified, it will be treated as a maximum bound of how many
+    columns the layout can have, before the auto-positioning wraps back to the beginning of the
+    next row. The \l columns property is only used when \l flow is  \c GridLayout.LeftToRight.
+
+    \code
+        GridLayout {
+            id: grid
+            columns: 3
+            Text { text: "Three" }
+            Text { text: "words" }
+            Text { text: "in" }
+            Text { text: "a" }
+            Text { text: "row" }
+        }
+    \endcode
+
+    The \l rows property works in a similar way, but items are auto-positioned vertically.
+    The \l rows property is only used when \l flow is  \c GridLayout.TopToBottom.
+
+    You can specify which cell you want an item to occupy by setting the \c Layout.row
+    and \c Layout.column properties. You can also specify the row span or column span by
+    setting the \c Layout.rowSpan or \c Layout.columnSpan properties.
+
+    When the layout is resized, items may grow or shrink. Due to this, items have a
+    minimum size, preferred size and a maximum size.
+
+    Minimum size can be specified with the
+    Layout.minimumWidth and Layout.minimumHeight properties. These properties are 0 by default.
+
+    Preferred size can be specified with the Layout.preferredWidth and Layout.preferredHeight
+    properties. If Layout.preferredWidth or Layout.preferredHeight is not specified, it will
+    use the items implicitWidth or implicitHeight as the items preferred size. Finally, if
+    neither of these properties are set, it will use the width and height properties of the item.
+
+    \note It is not recommended to have bindings to the width and height properties of items in a
+    GridLayout, since this would conflict with the goal of the GridLayout.
+
+    Maximum size can be specified with the Layout.maximumWidth and Layout.maximumHeight
+    properties. If not set, these properties will be interpreted as infinite.
+
+    \note They are not actually infinite, but simply set to a very high value. The result of
+    the arrangement is virtually the same as if it was infinite.
+
+    The \c Layout.fillWidth and \c Layout.fillHeight can either be
+    \c true or \c false. If it is \c false, the items size will be fixed to its preferred size.
+    Otherwise, it will grow or shrink between its minimum
+    and maximum bounds.
+
+    \sa RowLayout
+    \sa ColumnLayout
+
+*/
+
+
+
 QT_BEGIN_NAMESPACE
 
 static const qreal q_declarativeLayoutDefaultSpacing = 4.0;
@@ -307,6 +392,12 @@ QQuickGridLayout::QQuickGridLayout(QQuickItem *parent /* = 0*/)
     d->engine.setSpacing(q_declarativeLayoutDefaultSpacing, Qt::Horizontal | Qt::Vertical);
 }
 
+/*!
+    \qmlproperty double GridLayout::columnSpacing
+
+    This property holds the spacing between each column.
+    The default value is 4.
+*/
 qreal QQuickGridLayout::columnSpacing() const
 {
     Q_D(const QQuickGridLayout);
@@ -324,6 +415,12 @@ void QQuickGridLayout::setColumnSpacing(qreal spacing)
     invalidate();
 }
 
+/*!
+    \qmlproperty double GridLayout::rowSpacing
+
+    This property holds the spacing between each row.
+    The default value is 4.
+*/
 qreal QQuickGridLayout::rowSpacing() const
 {
     Q_D(const QQuickGridLayout);
@@ -341,6 +438,13 @@ void QQuickGridLayout::setRowSpacing(qreal spacing)
     invalidate();
 }
 
+/*!
+    \qmlproperty int GridLayout::columns
+
+    This property holds the column bound for items positioned if \l flow is
+    \c GridLayout.LeftToRight.
+    The default value is treated as infinite.
+*/
 int QQuickGridLayout::columns() const
 {
     Q_D(const QQuickGridLayout);
@@ -357,6 +461,13 @@ void QQuickGridLayout::setColumns(int columns)
     emit columnsChanged();
 }
 
+
+/*!
+    \qmlproperty int GridLayout::rows
+
+    This property holds the row bound for items positioned if \l flow is \c GridLayout.TopToBottom.
+    The default value is treated as infinite.
+*/
 int QQuickGridLayout::rows() const
 {
     Q_D(const QQuickGridLayout);
@@ -373,6 +484,27 @@ void QQuickGridLayout::setRows(int rows)
     emit rowsChanged();
 }
 
+
+/*!
+    \qmlproperty enumeration GridLayout::flow
+
+    This property holds the flow direction of items that does not have an explicit cell
+    position set.
+    It is used together with the \l columns or \l rows property, where
+    they specify when flow is reset to the next row or column respectively.
+
+    Possible values are:
+
+    \list
+    \li GridLayout.LeftToRight (default) - Items are positioned next to
+       each other, then wrapped to the next line.
+    \li GridLayout.TopToBottom - Items are positioned next to each
+       other from top to bottom, then wrapped to the next column.
+    \endlist
+
+    \sa rows
+    \sa columns
+*/
 QQuickGridLayout::Flow QQuickGridLayout::flow() const
 {
     Q_D(const QQuickGridLayout);
@@ -516,6 +648,19 @@ QQuickLinearLayout::QQuickLinearLayout(Qt::Orientation orientation,
     d->engine.setSpacing(d->spacing, Qt::Horizontal | Qt::Vertical);
 }
 
+/*!
+    \qmlproperty double RowLayout::spacing
+
+    This property holds the spacing between each cell.
+    The default value 4.
+*/
+/*!
+    \qmlproperty double ColumnLayout::spacing
+
+    This property holds the spacing between each cell.
+    The default value 4.
+*/
+
 qreal QQuickLinearLayout::spacing() const
 {
     Q_D(const QQuickLinearLayout);