layouts.qdoc

Go to the documentation of this file.

// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtquick-usecase-layouts.html
\meta {keywords} {qmltopic}
\title Positioners and layouts
\keyword Use Case - Positioners and Layouts In QML
\brief Example of how to create layouts for visual components in a QML application
\ingroup explanations-programminglanguages
 
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
       {Red square positioned using direct x and y coordinates}
 
 
\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
       {Green and orange rectangles positioned using anchors}
 
 
\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}.
 
\snippet qmlapp/usecases/layouts.qml import
\snippet qmlapp/usecases/layouts.qml positioners
 
\image qmlapp/qml-uses-layouts-positioners.png
       {Red, green, and blue squares arranged in a row using positioners}
 
\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 [QML] {GridLayout} can
be resized and its format is 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.
 
*/