diff options
Diffstat (limited to 'src/quick/doc/src')
-rw-r--r-- | src/quick/doc/src/concepts/layouts/qtquicklayouts-index.qdoc | 54 | ||||
-rw-r--r-- | src/quick/doc/src/concepts/layouts/qtquicklayouts-overview.qdoc | 176 | ||||
-rw-r--r-- | src/quick/doc/src/concepts/layouts/qtquicklayouts.qdoc | 46 | ||||
-rw-r--r-- | src/quick/doc/src/examples.qdoc | 2 | ||||
-rw-r--r-- | src/quick/doc/src/includes/layout.qdocinc | 18 | ||||
-rw-r--r-- | src/quick/doc/src/qmltypereference.qdoc | 6 | ||||
-rw-r--r-- | src/quick/doc/src/qtquick.qdoc | 1 |
7 files changed, 299 insertions, 4 deletions
diff --git a/src/quick/doc/src/concepts/layouts/qtquicklayouts-index.qdoc b/src/quick/doc/src/concepts/layouts/qtquicklayouts-index.qdoc new file mode 100644 index 0000000000..0be66fad2c --- /dev/null +++ b/src/quick/doc/src/concepts/layouts/qtquicklayouts-index.qdoc @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2016 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** 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 The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtquicklayouts-index.html + \title Qt Quick Layouts + \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. + + Visit the \l{Qt Quick Layouts Overview} page to get started. + + \section1 Layouts + + \annotatedlist layouts + + \section1 Related information + + \list + \li \l{Qt Quick} + \li \l{Qt Quick Layouts Overview} + \li \l{Qt Quick Layouts - Basic Example} + \li \l{Qt Quick Layouts QML Types}{Qt Quick Layouts QML Types} + \endlist +*/ diff --git a/src/quick/doc/src/concepts/layouts/qtquicklayouts-overview.qdoc b/src/quick/doc/src/concepts/layouts/qtquicklayouts-overview.qdoc new file mode 100644 index 0000000000..20a6d131f5 --- /dev/null +++ b/src/quick/doc/src/concepts/layouts/qtquicklayouts-overview.qdoc @@ -0,0 +1,176 @@ +/**************************************************************************** +** +** Copyright (C) 2016 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** 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 The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.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 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.2 + \endcode + + \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 qml/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. + + \section2 Specifying Preferred Size + For each item, the effective preferred size may come from one of several candidate properties. + For determining the effective preferred size, it will query these candidate properties in the + following order, and use the first candidate with a valid width or height. + + \table + \header + \li Candidate properties + \li Description + \row + \li \l{Layout::preferredWidth}{Layout.preferredWidth} or + \l{Layout::preferredHeight}{Layout.preferredHeight} + \li These properties are supposed to be modified by the application if the default implicit + size does not give the optimal arrangement. + \row + \li \l{Item::implicitWidth}{implicitWidth} or \l{Item::implicitHeight}{implicitHeight} + \li These properties are supposed to be supplied by each item to give a meaningful ideal size, + for example the size needed to display all the contents of a \l Text type. + An implicit width or height of \c 0 is interpreted as invalid. + \row + \li \l{Item::width}{width} and \l{Item::height}{height} + \li If none of the above properties are valid, the layout will resort to the + \l{Item::width}{width} and \l{Item::height}{height} properties. + \endtable + + An item can specify \l{Layout::preferredWidth}{Layout.preferredWidth} without having to specify + \l{Layout::preferredHeight}{Layout.preferredHeight}. In this case, the effective preferred + height will be determined from the \l{Item::implicitHeight}{implicitHeight} (or ultimately + \l{Item::height}{height}). + + \note Resorting to \l{Item::width}{width} or \l{Item::height}{height} properties is only + provided as a final fallback. If you want to override the preferred size, it is recommended to + use \l{Layout::preferredWidth}{Layout.preferredWidth} or + \l{Layout::preferredHeight}{Layout.preferredHeight}. Relying on the \l{Item::width}{width} or + \l{Item::height}{height} properties for specifying the preferred size might give some + unexpected behavior. For instance, changing the \l{Item::width}{width} or + \l{Item::height}{height} properties won't trigger a layout rearrangement. Also, when the layout + is forced to do a full rebuild it might use the actual width and height, and not the width and + height specified in the QML file. + + + \section1 Connecting windows and layouts + You can just use normal anchoring concepts to ensure that the layout will follow the window + resizing. + + \snippet qml/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 qml/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 qml/windowconstraints.qml binddefaultsize +*/ diff --git a/src/quick/doc/src/concepts/layouts/qtquicklayouts.qdoc b/src/quick/doc/src/concepts/layouts/qtquicklayouts.qdoc new file mode 100644 index 0000000000..8f390c83db --- /dev/null +++ b/src/quick/doc/src/concepts/layouts/qtquicklayouts.qdoc @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2016 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** 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 The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \qmlmodule QtQuick.Layouts 1.3 + \title Qt Quick Layouts QML Types + \ingroup qmlmodules + \brief Provides QML types for arranging QML items in a user interface. + + The \l{Qt Quick Layouts} module provides QML types for arranging + QML items in a user interface. + These QML types work in conjunction with \l{Qt Quick} and + \l{Qt Quick Controls}. + + The QML types can be imported into your application using the + following import statement in your .qml file. + + \code + import QtQuick.Layouts 1.3 + \endcode + +*/ diff --git a/src/quick/doc/src/examples.qdoc b/src/quick/doc/src/examples.qdoc index e69c2f6551..e41b472ee1 100644 --- a/src/quick/doc/src/examples.qdoc +++ b/src/quick/doc/src/examples.qdoc @@ -135,7 +135,7 @@ Creator. \div {class="doc-column"} \b{Layouts and Views} \list - \li \l{Qt Quick Controls - Basic Layouts Example}{Basic Layouts} + \li \l{Qt Quick Layouts - Basic Example} \li \l{Qt Quick Examples - Positioners}{Positioners} \li \l{Qt Quick Examples - Views}{Views} \li \l{Qt Quick Examples - Window and Screen}{Windows and Screen} diff --git a/src/quick/doc/src/includes/layout.qdocinc b/src/quick/doc/src/includes/layout.qdocinc new file mode 100644 index 0000000000..723fbc515a --- /dev/null +++ b/src/quick/doc/src/includes/layout.qdocinc @@ -0,0 +1,18 @@ +//! [attached-properties] + +\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} +\li \l{Layout::margins}{Layout.margins} +\li \l{Layout::topMargin}{Layout.leftMargin} +\li \l{Layout::rightMargin}{Layout.rightMargin} +\li \l{Layout::topMargin}{Layout.topMargin} +\li \l{Layout::bottomMargin}{Layout.bottomMargin} + +//! [attached-properties] diff --git a/src/quick/doc/src/qmltypereference.qdoc b/src/quick/doc/src/qmltypereference.qdoc index 630e0f58bc..6e6e66e026 100644 --- a/src/quick/doc/src/qmltypereference.qdoc +++ b/src/quick/doc/src/qmltypereference.qdoc @@ -26,7 +26,7 @@ ****************************************************************************/ /*! -\qmlmodule QtQuick 2.5 +\qmlmodule QtQuick 2.7 \title Qt Quick QML Types \ingroup qmlmodules \brief Provides graphical QML types. @@ -34,11 +34,11 @@ The \l{Qt Quick} module provides graphical primitive types. These types are only available in a QML document if that document imports the \c QtQuick namespace. -The current version of the \c QtQuick module is version 2.5, and thus it may be +The current version of the \c QtQuick module is version 2.7, and thus it may be imported via the following statement: \qml -import QtQuick 2.5 +import QtQuick 2.7 \endqml Visit the \l {Qt Quick} module documentation for more diff --git a/src/quick/doc/src/qtquick.qdoc b/src/quick/doc/src/qtquick.qdoc index 98a77a48d8..4bdd02241d 100644 --- a/src/quick/doc/src/qtquick.qdoc +++ b/src/quick/doc/src/qtquick.qdoc @@ -101,6 +101,7 @@ Additional Qt Quick information: containing a JavaScript interface for an SQLite database \li \l{Qt Quick Particles QML Types}{Particles} - provides a particle system for Qt Quick + \li \l{Qt Quick Layouts}{Layouts} - provides layouts for arranging Qt Quick items \li \l{Qt Quick Window QML Types}{Window} - contains types for creating top-level windows and accessing screen information \li \l{Qt Quick Dialogs}{Dialogs} - contains types for creating and |