Commit c5d39cb1 authored by Jan Arve Saether's avatar Jan Arve Saether Committed by The Qt Project
Browse files

Several improvements to documentation


* List all applicable attached properties for each layout
* Move the stuff that describes min,pref and max sizes from GridLayout
  to the Layout docs.
* Document that all layouts \inherits Item. (Even if they don't directly
  inherit, this is consistent with how the positioners are documented)
* Add some links to Row, Column and Grid where appropriate
* Use \qmlattachedproperty instead of \qmlproperty for the attached
  properties. (Again, consistent with how the Positioners attached
  properties are documented)
* Change POSITIVE_INFINITE to the correct POSITIVE_INFINITY

Change-Id: Ia9272faa479b48a97300b031402c0380ca113d7b
Reviewed-by: default avatarCaroline Chao <caroline.chao@digia.com>
Reviewed-by: default avatarJerome Pasion <jerome.pasion@digia.com>
parent c94a6f44
No related merge requests found
Showing with 96 additions and 44 deletions
...@@ -29,7 +29,14 @@ ...@@ -29,7 +29,14 @@
\page qtquicklayouts-index.html \page qtquicklayouts-index.html
\title Qt Quick Layouts \title Qt Quick Layouts
\brief A module with a set of QML elements that arranges QML items in an user interface. \brief A module with a set of QML elements that arrange QML items in a user interface.
Qt Quick Layouts are a set of QML types used to arrange items in a user interface. In contrast
to \l{Item Positioners}{positioners}, Qt Quick Layouts can also resize their items. This makes
them well suited for resizable user interfaces. Since layouts are items they can consequently
be nested.
The module is new in Qt 5.1 and requires \l{Qt Quick} 2.1.
\section1 Getting started \section1 Getting started
...@@ -40,9 +47,6 @@ ...@@ -40,9 +47,6 @@
\endcode \endcode
\section1 Layouts \section1 Layouts
Layouts are items that are used to arrange items in the user interface. The layout is dynamic -
when the layout changes geometry it will typically influence the arrangement of its child
items. Since a layout is an item, layouts can consequently be nested.
\annotatedlist layouts \annotatedlist layouts
......
...@@ -60,11 +60,33 @@ ...@@ -60,11 +60,33 @@
For instance, you can specify \l minimumWidth, \l preferredWidth, and For instance, you can specify \l minimumWidth, \l preferredWidth, and
\l maximumWidth if the default values are not satisfactory. \l maximumWidth if the default values are not satisfactory.
\l fillWidth and \l fillHeight allows you to specify whether an item should When a layout is resized, items may grow or shrink. Due to this, items have a
fill the cell(s) it occupies. This allows it to stretch between \l minimumWidth \l{Layout::minimumWidth}{minimum size}, \l{Layout::preferredWidth}{preferred size} and a
and \l maximumWidth (or \l minimumHeight and \l maximumHeight if \l fillHeight is \c true). \l{Layout::maximumWidth}{maximum size}.
For each item, preferred size may come from one of several sources. It can be specified with
the \l preferredWidth and \l preferredHeight properties. If these properties are not
specified, it will use the item's \l{Item::implicitWidth}{implicitWidth} or
\l{Item::implicitHeight}{implicitHeight} as the preferred size.
Finally, if neither of these properties are set, it will use the \l{Item::width}{width} and
\l{Item::height}{height} properties of the item. Note that is provided only as a final
fallback. If you want to override the preferred size, you should use
\l preferredWidth or \l preferredHeight.
If minimum size have not been explicitly specified on an item, the size is set to \c 0.
If maximum size have not been explicitly specified on an item, the size is set to
\c Number.POSITIVE_INFINITY.
For layouts, the implicit minimum and maximum size depends on the content of the layouts.
The \l fillWidth and \l fillHeight properties can either be \c true or \c false. If it is \c
false, the item's size will be fixed to its preferred size. Otherwise, it will grow or shrink
between its minimum and maximum size as the layout is resized.
\note It is not recommended to have bindings to the x, y, width, or height properties of items
in a layout, since this would conflict with the goal of the Layout, and also cause binding
loops.
If \l fillWidth or \l fillHeight is \c false, the items' size will be fixed to its preferred size.
\sa GridLayout \sa GridLayout
\sa RowLayout \sa RowLayout
...@@ -100,7 +122,7 @@ QQuickLayoutAttached::QQuickLayoutAttached(QObject *parent) ...@@ -100,7 +122,7 @@ QQuickLayoutAttached::QQuickLayoutAttached(QObject *parent)
} }
/*! /*!
\qmlproperty real Layout::minimumWidth \qmlattachedproperty real Layout::minimumWidth
This property holds the maximum width of an item in a layout. This property holds the maximum width of an item in a layout.
The default value is the items implicit minimum width. The default value is the items implicit minimum width.
...@@ -129,7 +151,7 @@ void QQuickLayoutAttached::setMinimumWidth(qreal width) ...@@ -129,7 +151,7 @@ void QQuickLayoutAttached::setMinimumWidth(qreal width)
} }
/*! /*!
\qmlproperty real Layout::minimumHeight \qmlattachedproperty real Layout::minimumHeight
The default value is the items implicit minimum height. The default value is the items implicit minimum height.
...@@ -156,7 +178,7 @@ void QQuickLayoutAttached::setMinimumHeight(qreal height) ...@@ -156,7 +178,7 @@ void QQuickLayoutAttached::setMinimumHeight(qreal height)
} }
/*! /*!
\qmlproperty real Layout::preferredWidth \qmlattachedproperty real Layout::preferredWidth
This property holds the preferred width of an item in a layout. This property holds the preferred width of an item in a layout.
If the preferred width is -1 it will be ignored, and the layout If the preferred width is -1 it will be ignored, and the layout
...@@ -177,7 +199,7 @@ void QQuickLayoutAttached::setPreferredWidth(qreal width) ...@@ -177,7 +199,7 @@ void QQuickLayoutAttached::setPreferredWidth(qreal width)
} }
/*! /*!
\qmlproperty real Layout::preferredHeight \qmlattachedproperty real Layout::preferredHeight
This property holds the preferred height of an item in a layout. This property holds the preferred height of an item in a layout.
If the preferred height is -1 it will be ignored, and the layout If the preferred height is -1 it will be ignored, and the layout
...@@ -198,14 +220,14 @@ void QQuickLayoutAttached::setPreferredHeight(qreal height) ...@@ -198,14 +220,14 @@ void QQuickLayoutAttached::setPreferredHeight(qreal height)
} }
/*! /*!
\qmlproperty real Layout::maximumWidth \qmlattachedproperty real Layout::maximumWidth
This property holds the maximum width of an item in a layout. This property holds the maximum width of an item in a layout.
The default value is the items implicit maximum width. The default value is the items implicit maximum width.
If the item is a layout, the implicit maximum width will be the maximum width the layout can If the item is a layout, the implicit maximum width will be the maximum width the layout can
have without any of its items grow beyond their maximum width. have without any of its items grow beyond their maximum width.
The implicit maximum width for any other item is \c Number.POSITIVE_INFINITE. The implicit maximum width for any other item is \c Number.POSITIVE_INFINITY.
Setting this value to -1 will reset the width back to its implicit maximum width. Setting this value to -1 will reset the width back to its implicit maximum width.
...@@ -226,13 +248,13 @@ void QQuickLayoutAttached::setMaximumWidth(qreal width) ...@@ -226,13 +248,13 @@ void QQuickLayoutAttached::setMaximumWidth(qreal width)
} }
/*! /*!
\qmlproperty real Layout::maximumHeight \qmlattachedproperty real Layout::maximumHeight
The default value is the items implicit maximum height. The default value is the items implicit maximum height.
If the item is a layout, the implicit maximum height will be the maximum height the layout can If the item is a layout, the implicit maximum height will be the maximum height the layout can
have without any of its items grow beyond their maximum height. have without any of its items grow beyond their maximum height.
The implicit maximum height for any other item is \c Number.POSITIVE_INFINITE. The implicit maximum height for any other item is \c Number.POSITIVE_INFINITY.
Setting this value to -1 will reset the height back to its implicit maximum height. Setting this value to -1 will reset the height back to its implicit maximum height.
...@@ -299,7 +321,7 @@ void QQuickLayoutAttached::setMaximumImplicitSize(const QSizeF &sz) ...@@ -299,7 +321,7 @@ void QQuickLayoutAttached::setMaximumImplicitSize(const QSizeF &sz)
} }
/*! /*!
\qmlproperty bool Layout::fillWidth \qmlattachedproperty bool Layout::fillWidth
If this property is \c true, the item will be as wide as possible while respecting If this property is \c true, the item will be as wide as possible while respecting
the given constraints. If the property is \c false, the item will have a fixed width the given constraints. If the property is \c false, the item will have a fixed width
...@@ -319,7 +341,7 @@ void QQuickLayoutAttached::setFillWidth(bool fill) ...@@ -319,7 +341,7 @@ void QQuickLayoutAttached::setFillWidth(bool fill)
} }
/*! /*!
\qmlproperty bool Layout::fillHeight \qmlattachedproperty bool Layout::fillHeight
If this property is \c true, the item will be as tall as possible while respecting If this property is \c true, the item will be as tall as possible while respecting
the given constraints. If the property is \c false, the item will have a fixed height the given constraints. If the property is \c false, the item will have a fixed height
...@@ -339,7 +361,7 @@ void QQuickLayoutAttached::setFillHeight(bool fill) ...@@ -339,7 +361,7 @@ void QQuickLayoutAttached::setFillHeight(bool fill)
} }
/*! /*!
\qmlproperty int Layout::row \qmlattachedproperty int Layout::row
This property allows you to specify the row position of an item in a \l GridLayout. This property allows you to specify the row position of an item in a \l GridLayout.
...@@ -357,7 +379,7 @@ void QQuickLayoutAttached::setRow(int row) ...@@ -357,7 +379,7 @@ void QQuickLayoutAttached::setRow(int row)
} }
/*! /*!
\qmlproperty int Layout::column \qmlattachedproperty int Layout::column
This property allows you to specify the column position of an item in a \l GridLayout. This property allows you to specify the column position of an item in a \l GridLayout.
...@@ -376,7 +398,7 @@ void QQuickLayoutAttached::setColumn(int column) ...@@ -376,7 +398,7 @@ void QQuickLayoutAttached::setColumn(int column)
/*! /*!
\qmlproperty Qt.Alignment Layout::alignment \qmlattachedproperty Qt.Alignment Layout::alignment
This property allows you to specify the alignment of an item within the cell(s) it occupies. This property allows you to specify the alignment of an item within the cell(s) it occupies.
...@@ -385,7 +407,7 @@ void QQuickLayoutAttached::setColumn(int column) ...@@ -385,7 +407,7 @@ void QQuickLayoutAttached::setColumn(int column)
/*! /*!
\qmlproperty int Layout::rowSpan \qmlattachedproperty int Layout::rowSpan
This property allows you to specify the row span of an item in a \l GridLayout. This property allows you to specify the row span of an item in a \l GridLayout.
...@@ -397,7 +419,7 @@ void QQuickLayoutAttached::setColumn(int column) ...@@ -397,7 +419,7 @@ void QQuickLayoutAttached::setColumn(int column)
/*! /*!
\qmlproperty int Layout::columnSpan \qmlattachedproperty int Layout::columnSpan
This property allows you to specify the column span of an item in a \l GridLayout. This property allows you to specify the column span of an item in a \l GridLayout.
......
...@@ -48,33 +48,63 @@ ...@@ -48,33 +48,63 @@
/*! /*!
\qmltype RowLayout \qmltype RowLayout
\instantiates QQuickRowLayout \instantiates QQuickRowLayout
\inherits Item
\inqmlmodule QtQuick.Layouts 1.0 \inqmlmodule QtQuick.Layouts 1.0
\ingroup layouts \ingroup layouts
\brief Identical to \l GridLayout, but having only one row. \brief Identical to \l GridLayout, but having only one row.
It is available as a convenience for developers, as it offers a cleaner API. It is available as a convenience for developers, as it offers a cleaner API.
Items in a RowLayout support these attached properties:
\list
\li \l{Layout::minimumWidth}{Layout.minimumWidth}
\li \l{Layout::minimumHeight}{Layout.minimumHeight}
\li \l{Layout::preferredWidth}{Layout.preferredWidth}
\li \l{Layout::preferredHeight}{Layout.preferredHeight}
\li \l{Layout::maximumWidth}{Layout.maximumWidth}
\li \l{Layout::maximumHeight}{Layout.maximumHeight}
\li \l{Layout::fillWidth}{Layout.fillWidth}
\li \l{Layout::fillHeight}{Layout.fillHeight}
\li \l{Layout::alignment}{Layout.alignment}
\endlist
\sa ColumnLayout \sa ColumnLayout
\sa GridLayout \sa GridLayout
\sa Row
*/ */
/*! /*!
\qmltype ColumnLayout \qmltype ColumnLayout
\instantiates QQuickColumnLayout \instantiates QQuickColumnLayout
\inherits Item
\inqmlmodule QtQuick.Layouts 1.0 \inqmlmodule QtQuick.Layouts 1.0
\ingroup layouts \ingroup layouts
\brief Identical to \l GridLayout, but having only one column. \brief Identical to \l GridLayout, but having only one column.
It is available as a convenience for developers, as it offers a cleaner API. It is available as a convenience for developers, as it offers a cleaner API.
Items in a ColumnLayout support these attached properties:
\list
\li \l{Layout::minimumWidth}{Layout.minimumWidth}
\li \l{Layout::minimumHeight}{Layout.minimumHeight}
\li \l{Layout::preferredWidth}{Layout.preferredWidth}
\li \l{Layout::preferredHeight}{Layout.preferredHeight}
\li \l{Layout::maximumWidth}{Layout.maximumWidth}
\li \l{Layout::maximumHeight}{Layout.maximumHeight}
\li \l{Layout::fillWidth}{Layout.fillWidth}
\li \l{Layout::fillHeight}{Layout.fillHeight}
\li \l{Layout::alignment}{Layout.alignment}
\endlist
\sa RowLayout \sa RowLayout
\sa GridLayout \sa GridLayout
\sa Column
*/ */
/*! /*!
\qmltype GridLayout \qmltype GridLayout
\instantiates QQuickGridLayout \instantiates QQuickGridLayout
\inherits Item
\inqmlmodule QtQuick.Layouts 1.0 \inqmlmodule QtQuick.Layouts 1.0
\ingroup layouts \ingroup layouts
\brief Provides a way of dynamically arranging items in a grid. \brief Provides a way of dynamically arranging items in a grid.
...@@ -112,31 +142,27 @@ ...@@ -112,31 +142,27 @@
specify the row span or column span by setting the \l{Layout::rowSpan}{Layout.rowSpan} or specify the row span or column span by setting the \l{Layout::rowSpan}{Layout.rowSpan} or
\l{Layout::columnSpan}{Layout.columnSpan} properties. \l{Layout::columnSpan}{Layout.columnSpan} properties.
When the layout is resized, items may grow or shrink. Due to this, items have a
\l{Layout::minimumWidth}{minimum size}, \l{Layout::preferredWidth}{preferred size} and a
\l{Layout::maximumWidth}{maximum size}.
Preferred size may come from one of several sources. It can be specified with the Items in a GridLayout support these attached properties:
\l{Layout::preferredWidth}{Layout.preferredWidth} and \list
\l{Layout::preferredHeight}{Layout.preferredHeight} properties. If these properties are not \li \l{Layout::row}{Layout.row}
specified, it will use the items' \l{Item::implicitWidth}{implicitWidth} or \li \l{Layout::column}{Layout.column}
\l{Item::implicitHeight}{implicitHeight} as the preferred size. \li \l{Layout::rowSpan}{Layout.rowSpan}
Finally, if neither of these properties are set, it will use the \l{Item::width}{width} and \li \l{Layout::columnSpan}{Layout.columnSpan}
\l{Item::height}{height} properties of the item. Note that is provided only as a final \li \l{Layout::minimumWidth}{Layout.minimumWidth}
fallback. If you want to override the preferred size, you should use \li \l{Layout::minimumHeight}{Layout.minimumHeight}
\l{Layout::preferredWidth}{Layout.preferredWidth} or \li \l{Layout::preferredWidth}{Layout.preferredWidth}
\l{Layout::preferredHeight}{Layout.preferredHeight}. \li \l{Layout::preferredHeight}{Layout.preferredHeight}
\li \l{Layout::maximumWidth}{Layout.maximumWidth}
The \l{Layout::fillWidth}{Layout.fillWidth} and \l{Layout::fillHeight}{Layout.fillHeight} can \li \l{Layout::maximumHeight}{Layout.maximumHeight}
either be \c true or \c false. If it is \c false, the items size will be fixed to its preferred \li \l{Layout::fillWidth}{Layout.fillWidth}
size. Otherwise, it will grow or shrink between its minimum and maximum size. \li \l{Layout::fillHeight}{Layout.fillHeight}
\li \l{Layout::alignment}{Layout.alignment}
\note It is not recommended to have bindings to the width and height properties of items in a \endlist
GridLayout, since this would conflict with the goal of the GridLayout.
\sa RowLayout \sa RowLayout
\sa ColumnLayout \sa ColumnLayout
\sa Grid
*/ */
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment