Qt Reference Documentation

Use the Layout Features of QML

Layout Managers

For a given form factor, top level layout structure definitions, or component layout structure definitions, should in general be defined in a proportional way using a combination of

  • anchors within an Item
  • Row, Column, or Grid
  • simple javascript expressions

An example of a simple javascript expression would be: width: Math.round(parent.width / 3.0).

These basic building blocks, along with the powerful evaluation capabilities of javascript expressions within every QML binding, are designed to allow the majority of the layout structure definition to be defined in a Device Profile independent way.

There are some limitations of the basic grid type layouts. They are designed to accommodate a number of Items, but use the current sizes of those items. There is a similar issue with the basic anchor type layout. In particular, it can be difficult to spread a number of child items proportionately across an area of their container.

By combining the features of the layout managers with simple javascript expressions, a richer variety of designs can be expressed, without having to rely upon additional layout measurements specifc to each Device Profile.

Examples

For example, in the ScaleFM application, there is a layout that uses a helper item to define margins:

 Item {
     id: helper
     anchors { fill: parent; margins: appStyle.marginSize }
 }

Then the helper is used to share the available space:

 State {
     when: (true)
 AnchorChanges { target: stationList; anchors.left: undefined; anchors.top: frequencyArea.bottom; anchors.bottom: helper.bottom }
                 ...
 PropertyChanges { target: stationList; width: Math.round(helper.width * appStyle.stationListRatio) }
 }

Here are some things not to do with layouts:

  • Don't define complex javascript functions that are regularly evaluated. This will cause poor performance, particularly during animated transitions.
  • Don't define all of your layouts using x, y, width and height. Reserve this for items that cannot easily be defined using anchors (anchors are evaluated in a more efficient way).
  • Don't make assumptions about the container size, or about the size of child items. Try to make flexible layout definitions that can absorb changes in the available space.

See the following examples:

for more information on basic layout usage.

Right to Left Layouts

Right to Left layout functionality is provided by Qt Quick, and is supported by Qt Quick Components. See Qt Quick Right to Left Support for more information.

Note: The ToolBarLayout component is designed to not support this feature, as it is a requirement that the visual order of the tools is not mirrored when mirroring is enabled.

This documentation was introduced in Qt Quick Components 1.1.

Implicit Size

Many of the Qt Quick Components define their implicit size. This means that they will adopt a size that reflects their contents (and other factors such as the Platform Style), unless otherwise overridden by declaration or by a containing layout manager.

For more information, see the documentation for Qt Quick Implicit Size Support.