Positioning Items

The position of an item in a UI can be either absolute or relative to other items. The visual types exist at a particular location in the screen coordinate system at any instant in time. The x and y coordinates of a visual item are relative to those of its visual parent, with the top-left corner having the coordinate (0, 0).

If you are designing a static UI, manual positioning provides the most efficient form of positioning items. For a dynamic UI, you can employ the following positioning methods:

Setting Bindings

Property binding is a declarative way of specifying the value of a property. Binding allows a property value to be expressed as a JavaScript expression that defines the value relative to other property values or data accessible in the application. The property value is automatically kept up to date if the other properties or data values change.

Property bindings are created implicitly in QML whenever a property is assigned a JavaScript expression. To set JavaScript expressions as values of properties in the Properties view, select the (Actions) menu next to a property, and then select Set Binding.

"Type properties context menu"

In Binding Editor, select an item and a property from lists of available items and their properties.

"Binding Editor"

Alternatively, start typing a string and press Ctrl+Space to display a list of properties, IDs, and code snippets. When you enter a period (.) after a property name, a list of available values is displayed. Press Enter to accept the first suggestion in the list and to complete the code.

When a binding is set, the Actions menu icon changes to . To remove bindings, select Actions > Reset.

You can set bindings also in the Connections view. For more information, see Adding Bindings Between Properties.

For more information on the JavaScript environment provided by QML, see Integrating QML and JavaScript.

Bindings are a black box for Qt Creator and using them might have a negative impact on performance, so consider setting anchors and margins for items, instead. For example, instead of setting parent.width for an item, you could anchor the item to its sibling items on the left and the right.

Setting Anchors and Margins

In an anchor-based layout, each QML type can be thought of as having a set of invisible anchor lines: top, bottom, left, right, fill, horizontal center, vertical center, and baseline.

In the Layout tab you can set anchors and margins for items. To set the anchors of an item, click the anchor buttons. You can combine the top/bottom, left/right, and horizontal/vertical anchors to anchor items in the corners of the parent item or center them horizontally or vertically within the parent item.

"Anchor buttons"

For convenience, you can click the (Fill to Parent) toolbar button to apply fill anchors to an item and the (Reset Anchors) button to reset the anchors to their saved state.

You can specify the baseline anchor in Text Editor.

For performance reasons, you can only anchor an item to its siblings and direct parent. By default, an item is anchored to its parent when you use the anchor buttons. Select a sibling of the item in the Target field to anchor to it, instead.

Arbitrary anchoring is not supported. For example, you cannot specify: anchor.left: parent.right. You have to specify: anchor.left: parent.left. When you use the anchor buttons, anchors to the parent item are always specified to the same side. However, anchors to sibling items are specified to the opposite side: anchor.left: sibling.right. This allows you to keep sibling items together.

In the following image, Rectangle 2 is anchored to Rectangle 1 on its left and to the bottom of its parent.

"Anchoring sibling items"

The anchors for Rectangle 2 are specified as follows in code:

Rectangle {
    id: rectangle2
    anchors.left: rectangle1.right
    anchors.leftMargin: 10
    anchors.bottom: parent.bottom
    anchors.bottomMargin: 10
    //
}

Margins specify the amount of empty space to leave to the outside of an item. Margins only have meaning for anchors. They do not take any effect when using layouts or absolute positioning.

Aligning and Distributing Items

When you're working with a group of items, you can select them to align and distribute them evenly. As the positions of the items are fixed, you cannot apply these functions to anchored items. For scalability, you can anchor the aligned and distributed items when your design is ready.

"Aligning sibling items"

Select the buttons in the Align group to align the top/bottom or left/right edges of the items in the group to the one farthest away from the center of the group. For example, when left-aligning, the items are aligned to the leftmost item. You can also align the horizontal/vertical centers of items, or both, as in the image above.

In the Align to field, select whether to align the items in respect to the selection, the root item, or a key object that you select in the Key object field. The key object must be a part of the selection.

You can distribute either objects or the spacing between them. If the objects or spacing cannot be distributed to equal pixel values without ending up with half pixels, you receive a notification. You can either allow Qt Design Studio to distribute objects or spacing using the closest values possible or tweak your design so that the objects and spacing can be distributed perfectly.

When distributing objects, you can select whether the distance between them is calculated from their top/bottom or left/right edges or their horizontal/vertical center.

"Distribute objects buttons"

You can distribute spacing either evenly within a target area or at specified distances, calculated from a starting point.

You can select the orientation in which the objects are distributed evenly within the target area: horizontally along the x axis or vertically along the y axis.

"Distribute spacing evenly"

Alternatively, you can distribute spacing in pixels by selecting one of the starting point buttons: left/right or top/bottom edge of the target area, or its horizontal/vertical center. Note that some items might end up outside the target area.

"Distribute spacing in pixels"

You can set the space between objects in pixels. You can disable the distribution of spacing in pixels by clicking the button.

Using Positioners

Positioner items are container items that manage the positions of items. For many use cases, the best positioner to use is a simple column, row, flow, or grid. You can use the QML types available in the Qt Quick - Positioner section of Library to position the children of an item in these formations in the most efficient manner possible.

To position several items in a Column, Row, Flow, or Grid, select the items in Form Editor, and then select Position in the context menu.

Column Positioner

A Column positions its child items along a single column. It can be used as a convenient way to vertically position a series of items without using anchors.

"Column properties"

For all positioners, you can specify the spacing between the child items that they contain in the Spacing field.

In addition, you can specify the vertical and horizontal padding between content and the left, right, top, and bottom edges of items as values of the fields in the Padding group.

Row and Flow Positioners

A Row positions its child items along a single row. It can be used as a convenient way to horizontally position a series of items without using anchors.

The Flow type positions its child items like words on a page, wrapping them to create rows or columns of items.

"Flow properties"

For flow and row positioners, you can also set the direction of a flow to either left-to-right or top-to-bottom in the Flow field. Items are positioned next to to each other according to the value you set in the Layout direction field until the width or height of the Flow item is exceeded, then wrapped to the next row or column.

You can set the layout direction to either LeftToRight or RightToLeft in the Layout direction field. If the width of the row is explicitly set, the left anchor remains to the left of the row and the right anchor remains to the right of it.

Grid Positioner

A Grid creates a grid of cells that is large enough to hold all of its child items, and places these items in the cells from left to right and top to bottom. Each item is positioned at the top-left corner of its cell with position (0, 0).

Qt Creator generates the grid based on the positions of the child items in Form Editor. You can modify the number of rows and columns in the Rows and Columns fields.

"Grid properties"

In addition to the flow and layout direction, you can set the horizontal and vertical alignment of grid items. By default, grid items are vertically aligned to the top. Horizontal alignment follows the value of the Layout direction field. For example, when layout direction is set to LeftToRight, the items are aligned on the left.

To mirror the layout, set the layout direction to RightToLeft. To also mirror the horizontal alignment of items, select AlignRight in the Horizontal item alignment field.

Summary of Positioners

The following table lists the positioners that you can use to arrange items in UIs. They are available in the Qt Quick - Positioner section of Library.

IconNamePurpose
ColumnArranges its child items vertically.
RowArranges its child items horizontally.
GridArranges its child items so that they are aligned in a grid and are not overlapping.
FlowArranges its child items side by side, wrapping as necessary.

Using Layouts

Since Qt 5.1, you can use QML types in the Qt Quick Layouts module to arrange items in UIs. Unlike positioners, layouts manage both the positions and sizes of their child items, and are therefore well suited for dynamic and resizable UIs. However, this means that you should not specify fixed positions and sizes for the child items in the Geometry group in their properties, unless their implicit sizes are not satisfactory.

You can use anchors or the width and height properties of the layout itself to specify its size in respect to its non-layout parent item. However, do not anchor the child items within layouts.

To arrange several items in a column, row, grid, or Stack Layout, select the items in Form Editor, and then select Layout in the context menu.

You can also click the (Column Layout), (Row Layout), and (Grid Layout) toolbar buttons to apply layouts to the selected items.

To make an item within a layout as wide as possible while respecting the given constraints, select the item in Form Editor, and then select Layout > Fill Width in the context menu. To make the item as high as possible, select Fill Height.

Layout Properties

A Grid Layout type provides a way of dynamically arranging items in a grid. If the grid layout is resized, all its child items are rearranged. If you want a layout with just one row or one column, use the Row Layout or Column Layout type.

The child items of row and column layout items are automatically positioned either horizontally from left to right as rows or vertically from top to bottom as columns. The number of the child items determines the width of the row or the height of the column. You can specify the spacing between the child items in the Spacing field.

The child items of grid layout items are arranged according to the Flow property. When the direction of a flow is set to LeftToRight, child items are positioned next to to each other until the the number of Columns is reached. Then, the auto-positioning wraps back to the beginning of the next row.

"Grid Layout properties"

If you set the direction of the flow to TopToBottom, child items are auto-positioned vertically using the value of the Rows field to determine the maximum number of rows.

You can set the layout direction to either LeftToRight or RightToLeft in the Layout direction field. When you select RightToLeft, the alignment of the items will be mirrored.

You can specify the spacing between rows and columns in the Row spacing and Column spacing fields.

Stack Layout

To add items to a Stack Layout, select the button next to the type name in Form Editor. To move between items, select the (Previous) and (Next) buttons.

To add a tab bar to a stack layout, select Stacked Container > Add Tab Bar.

To raise or lower the stacking order of an item, select Stacked Container > Increase Index or Decrease Index.

Summary of Layouts

The following table lists the layout types that you can use to arrange items in UIs. They are available in the Qt Quick - Layouts section of Library.

IconNamePurpose
Column LayoutProvides a grid layout with only one column.
Row LayoutProvides a grid layout with only one row.
Grid LayoutProvides a way of dynamically arranging items in a grid.
Stack LayoutProvides a stack of items where only one item is visible at a time.

Organizing Items

The following table lists the UI controls that you can use to organize items in UIs (since Qt 5.7). They are available in the Qt Quick - Controls 2 section of Library.

IconNamePurpose
FrameA visual frame around a group of controls.
Group BoxA titled visual frame around a group of controls.
PageA styled page control with support for a header and footer.
PaneA background that matches the application style and theme.

© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.