From 6d70146b6d295b7704df6b3afe25c2550c6d9335 Mon Sep 17 00:00:00 2001
From: Jan Arve Saether <jan-arve.saether@digia.com>
Date: Thu, 21 Mar 2013 14:24:54 +0100
Subject: [PATCH] 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 | 2 +-
.../doc/src/qtquickcontrols-index.qdoc | 5 +
src/layouts/doc/qtquicklayouts-index.qdoc | 48 ++++++
src/layouts/doc/qtquicklayouts.qdocconf | 55 +++++++
src/layouts/layouts.pro | 4 +-
src/layouts/qquicklinearlayout.cpp | 153 +++++++++++++++++-
6 files changed, 260 insertions(+), 7 deletions(-)
create mode 100644 src/layouts/doc/qtquicklayouts-index.qdoc
create mode 100644 src/layouts/doc/qtquicklayouts.qdocconf
diff --git a/src/controls/doc/qtquickcontrols.qdocconf b/src/controls/doc/qtquickcontrols.qdocconf
index 943c5132c..d6268b335 100644
--- a/src/controls/doc/qtquickcontrols.qdocconf
+++ b/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/
diff --git a/src/controls/doc/src/qtquickcontrols-index.qdoc b/src/controls/doc/src/qtquickcontrols-index.qdoc
index 90f5fcce3..56b5b0d68 100644
--- a/src/controls/doc/src/qtquickcontrols-index.qdoc
+++ b/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
diff --git a/src/layouts/doc/qtquicklayouts-index.qdoc b/src/layouts/doc/qtquicklayouts-index.qdoc
new file mode 100644
index 000000000..7077e1d51
--- /dev/null
+++ b/src/layouts/doc/qtquicklayouts-index.qdoc
@@ -0,0 +1,48 @@
+/****************************************************************************
+**
+** 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
+
+*/
diff --git a/src/layouts/doc/qtquicklayouts.qdocconf b/src/layouts/doc/qtquicklayouts.qdocconf
new file mode 100644
index 000000000..c99744d8f
--- /dev/null
+++ b/src/layouts/doc/qtquicklayouts.qdocconf
@@ -0,0 +1,55 @@
+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
diff --git a/src/layouts/layouts.pro b/src/layouts/layouts.pro
index 20bcf20c1..e0d7f7751 100644
--- a/src/layouts/layouts.pro
+++ b/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)
diff --git a/src/layouts/qquicklinearlayout.cpp b/src/layouts/qquicklinearlayout.cpp
index c452e4fdc..f01a02685 100644
--- a/src/layouts/qquicklinearlayout.cpp
+++ b/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);
--
GitLab