1// Copyright (C) 2023 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page qtquicklayouts-responsive.html
6 \title Qt Quick Responsive Layouts
7 \brief A guideline to make Qt Quick Layouts adaptive to screen size.
9 Layouts are a good technique to make resizable user interfaces. However,
10 this approach has its limitations as we cannot shrink and expand items
11 limitless without sacrificing usability and aesthetics. At some point, it
12 makes more sense to reorganize, remove or add certain elements. Adapting to
13 different devices (e.g. phones and tables) and screen orientations
14 (landscape or portrait) can be implemented similarly. This is what
15 we usually understand as responsive layouts and \l {Qt Quick Layouts}
16 provide various APIs to implement them.
18 \section1 Static hierarchy, adaptive layout
20 Layouts have a hierarchy, which is usually defined by the declarative QML
21 code. For some simple responsive layouts, it is sufficient to keep the
22 hierarchy unmodified and instead just tweak some of the properties that
25 \section2 Declarative description
27 The simplest approach to change layouting is to modify layout properties
28 and \l {Layout} attached properties with small expressions. You can for
29 instance use ternary operators in order to modify the layout depending
31 \l {Item} properties, such as \l {Item::visible}{Item.visible},
32 hiding or showing various parts of the interface, can be modified the same
35 In the following snippet, this concept is used to change a two-column
36 layout into a single-column layout if the window width is smaller than a
39 \snippet layouts/responsiveDeclarative.qml document
41 The resulting layouts look like this, depending on the width of the window.
43 \div {class="float-right"}
44 \inlineimage simpleProxy.png
47 Various levels of layouts and items can be nested but \l {Item}{Items} can only be moved within a their \l{Item::parent}{Item.parent}.
51 The same result can be achieved with \l {Qt Quick States}. The upside of
52 using states is that the \l {Layout} properties for a specific layout are
53 collected at a single point in the QML file (at least the changing ones).
54 The previously shown example can be implemented as follows and the result
55 looks and behaves the exact same.
57 \snippet layouts/responsiveStates.qml document
59 \section2 LayoutItemProxy
61 A third approach is the application of the \l {LayoutItemProxy}. The
62 implementation of the previously shown minimalistic example can be found in
63 the type documentation. In contrast to previously shown solutions, the
64 \l {LayoutItemProxy} enables the declaration of completely separate layouts
65 for various form factors. Especially with more complex layouts this might be
66 useful to improve and maintain a reasonable source code structure.
68 Note, that the \l{LayoutItemProxy} API is a technical preview and might
69 be subject to change or removal in future Qt versions.
71 \section1 Adaptive hierarchy, adaptive layout
73 More complex reconstructions of the layout might require changes to
74 the hierarchy. A small stand-alone button in a small layout might be
75 combined with other buttons and put into a box of a larger layout. An item
76 that is fully visible in one layout, might require a \l {Flickable} in
77 another, smaller layout. In this scenario, it is best to rely on the \l {LayoutItemProxy}. The \l {LayoutItemProxy} allows to move \l{Item}{Items} across various hierarchy levels and between different \l{Item::parent}{Item.parent}.
79 The \l {Qt Quick Layouts - Responsive Layout Example} shows a case where an
80 item is moved between different hierarchy levels, put into a \l {Flickable}
81 in one case and on the top level in another layout. The two resulting
82 layouts look as follows.
84 \div {class="float-right"}
85 \image qtquicklayouts-example-responsivelayouts.png
89 \section1 Useful links: Consult your design guidelines
91 Many design guidelines offer help and tips to create responsive layouts.
92 Implementing the respective techniques is possible with the APIs mentioned
93 above. For further information we recommend the following links:
96 \li \l {https://developer.apple.com/design/human-interface-guidelines/layout}{Apple human interface guidelines}
97 \li \l {https://m3.material.io/foundations/layout/applying-layout/window-size-classes}{Material3 layouts}
98 \li \l {https://learn.microsoft.com/en-us/windows/apps/design/layout/responsive-design}{Microsoft Fluent responsive design techniques}
1.10.0