qt-everywhere-src-5.15.1/qtdoc/doc/src/qmlapp/usecases/layouts.qdoc

/****************************************************************************
**
** 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 qtquick-usecase-layouts.html
\title Use Case - Positioners and Layouts In QML
\brief Example of how to create layouts for visual components in a QML application

There are several ways to position items in QML.

Below is a brief overview. For more details, see \l {Important Concepts In Qt Quick - Positioning}.

\section1 Manual Positioning

Items can be placed at specific x,y coordinates on the screen by setting their x,y properties. This will
setup their position relative to the top left corner of their parent, according to the
\l {Concepts - Visual Coordinates in Qt Quick}{visual coordinate system} rules.

Combined with using \l{Property Binding}{bindings} instead of constant values for these properties, relative positioning is also easily
accomplished by setting the x and y coordinates to the appropriate bindings.

\snippet qmlapp/usecases/layouts.qml import
\snippet qmlapp/usecases/layouts.qml direct

\image qmlapp/qml-uses-layouts-direct.png


\section1 Anchors

The \c Item type provides the abilitiy to anchor to other \l Item types. There
are seven anchor lines for each item: \e left, \e right, \e{vertical center},
\e top, \e bottom, \e baseline and \e{horizontal center}. The three vertical
anchor lines can be anchored to any of the three vertical anchor lines of
another item, and the four horizontal anchor lines can be anchored to the
horizontal anchor lines of another item.

For full details, see \l {Positioning with Anchors} and the documentation of the \l{Item::anchors.top}{anchors property}.

\snippet qmlapp/usecases/layouts.qml import
\snippet qmlapp/usecases/layouts.qml anchors

\image qmlapp/qml-uses-layouts-anchors.png


\section1 Positioners

For the common case of wanting to \e position a set of types in a regular pattern, Qt Quick provides some positioner
types. Items placed in a positioner are automatically positioned in some way; for example, a \l [QML] Row positions items to be
horizontally adjacent (forming a row).

For full details see \l {Item Positioners} and the documentation for \l{Qt Positioning QML Types}{the positioner types}.

\snippet qmlapp/usecases/layouts.qml import
\snippet qmlapp/usecases/layouts.qml positioners

\image qmlapp/qml-uses-layouts-positioners.png

\section1 Layout Types

\e{Layout types} function in a similar way as positioners but allow further refinement or
restrictions to the layout. Specifically, the layout types allow you to:

\list
\li set the alignment of text and other items
\li resize and fill the allotted application areas automatically
\li set size constraints such as minimum or maximum dimensions
\li set the spacing between items within the layout
\endlist

\qml
    GroupBox {
        id: gridBox
        title: "Grid layout"
        Layout.fillWidth: true

        GridLayout {
            id: gridLayout
            rows: 3
            flow: GridLayout.TopToBottom
            anchors.fill: parent
            Label { text: "Line 1" }
            Label { text: "Line 2" }
            Label { text: "Line 3" }

            TextField { }
            TextField { }
            TextField { }

            TextArea {
                text: "This widget spans over three rows in the GridLayout.\n"
                      + "All items in the GridLayout are implicitly positioned from top to bottom."
                Layout.rowSpan: 3
                Layout.fillHeight: true
                Layout.fillWidth: true
            }
        }
    }
\endqml
The snippet above comes from the \l{Qt Quick Layouts - Basic Example}{Basic Layouts} example. The
snippet shows the simplicity of adding various fields and items in a layout. The \l GridLayout can
be resized and its format are customizable through various properties.

For more information about the layout types, visit:
\list
\li \l{Qt Quick Layouts Overview}
\li \l{Qt Quick Layouts - Basic Example}{Basic Layouts} example
\endlist

\note \l{Qt Quick Layouts} was introduced in Qt 5.1 and requires \l{Qt Quick} 2.1.

*/