|
|
              
Composing User Interfaces with QMLIn the previous chapter, we looked at the syntax of QML and the basic building blocks that are used to create user interfaces. For example, at a low level, we have seen that an item's x and y properties are used to position it within its parent item. However, when defining more complex user interfaces, especially those with items that will move or change size, we need a way to arrange items in a more systematic way. Anchors and Anchor LinesIn the previous examples, all the items have been given either absolute positions in the user interface or positions relative to their parents. For more flexibility, both at design-time and in the case where the user interface changes at run-time, we prefer to use anchors to arrange items. Anchors connect items together visually, creating relationships between their geometries. As a result, mixing absolute positioning and anchors is only recommended in cases where the constraints imposed by each approach do not conflict. Anchors can only be used to relate items with their parents, children or siblings. Anchoring within ItemsAnchors can be used to generally describe how items are positioned within the space occupied by their parents. Two of the anchors are used to place items in this way. The following example uses anchors to position a Text item in the center of a Rectangle. [Missing image declarative-qmlintro-anchors-centerin.png] In this case, the center of the text item is anchored to the center of its parent item by using the anchors.centerIn grouped property. This defines a high level description of the relationship between the two items. Similarly, the anchors.fill grouped property is used to describe the case where an item needs to fill the space provided by its parent. Note: When using anchors.centerIn and anchors.fill, the value of the anchor property is an item. Anchor LinesAt a lower level, anchors can be used to line up the edges of two items. In the following example, the Text item is centered within its parent, the Item that defines the user interface. The Rectangle uses anchors to define its position relative to the text item. [Missing image declarative-qmlintro-anchors-edges.png] By giving the text item the textItem identifier, we can refer to it when defining the anchors for the rectangle. We line up the right edge of the rectangle with the left edge of the text item, and line up their top edges. This example shows the use of anchor lines. Grouped properties are defined for key parts of each item, including its top, left, right and bottom edges, plus the lines running through the horizontal center and vertical center of the item. A baseline anchor line is also used for items that display text. Note: We connect anchor lines to other anchor lines, not to items. Anchors and Property BindingsSince the anchor definitions are property bindings, any changes to the position of an anchor will cause any connected anchors to move as well. This is illustrated by the following example, which places a red rectangle beneath a TextInput item and uses anchors to ensure that it is always the same width. [Missing image declarative-qmlintro-anchors-expanding1.png] The anchor lines on the left and right edges of the rectangle are connected to those of the text input item. Since the text can be modified by the user, the width of the item can change. The use of anchors causes the width of the rectangle to change as well. The Anchor-Based Layout in QML document covers the use of anchors in more detail. MarginsAlthough anchors are useful for lining up items, it is often useful to leave small gaps between the edges of adjacent items. The following example lines up an Image item with a Text item, but uses a margin to leave a gap between them. [Missing image declarative-qmlintro-anchors-margins.png] Note that the image also uses a margin to leave a gap between its left edge and the left edge of the user interface. Adding Rectangle items to the scene description, we can see the effects of the anchors and margins, with the image displaced from the left edge of its parent item and the text label displaced from the right edge of the image. Limitations and StrategiesAnchors allow the relationships between items to be described using simple declarations, maintaining a user interface layout when items move or change size. They are useful in most situations, but have limitations which need to be considered, and therefore it is a good idea to adopt strategies for using them. Limitations of AnchorsSince anchors can only be used to relate an item with its parent, children or siblings, care must be taken when referencing items in complex or deeply-nested user interfaces. Where there are lots of items to be arranged, it can be more productive to use positioners and repeaters, or models and views. Connections between anchors cannot be deleted and will override explicit declarations of positions and sizes using the x, y, width and height properties of items. Since anchors rely on property binding to ensure that items are dynamically updated if one of them changes, each anchor definition creates a new dependency on another item. Use of anchors therefore causes a dependency graph defining an order in which items will be updated. Problems can occur if circular dependencies are created between items. The following example shows this occurring with a parent item and its child. Strategies for UseIn order to reference an item with an anchor, it needs a way to be identified. Children of the item can refer to it as parent, but otherwise it needs to define an identifier. It is good practice to define identifiers for all the items that need to be positioned or referenced in some way unless those items can be referenced using the parent identifier. It is usually helpful to identify the fixed or dominant parts of the user interface and give those items identifiers so that dependent items can refer to them. This avoids potential issues with circular dependencies. In the example shown, the launchBox and cancelBox items are anchored within the top level item that contains the user interface. Each of these items contain an image and a text item that are anchored to their parent. [Missing image declarative-qmlintro-anchors-strategy-annotated.png] The above example shows how each item is anchored to its parent. This ensures that the dependencies introduced by the anchors all consistently point to each item's parent or a sibling. It is not always possible to ensure such simple dependencies between items. As a result, it is often necessary to consider other factors that determine how the use of anchors will affect the geometries of items. When positioning items using the horizontalCenter anchor, do not use the left or right anchors; define the width of the item instead, either as a fixed value or as a proportion of the parent item. Similarly, avoid using the top or bottom anchors with the verticalCenter anchor; set the height of the item instead. Items that define their own width and height based on their contents, like Image or TextInput, can be used with all kinds of anchors. Care must be taken to avoid imposing conflicting constraints on their dimensions. For example, using left and right anchors to position a text input item may be problematic because the item determines its own width and it may change. When defining an item that you want to stretch to fill the available space between other items, make sure that you anchor the stretchable item to items with well-defined or implicitly-defined sizes and not the other way round. The following example shows this with a Text item with an implicit size and a Rectangle that stretches to fill the remaining space in its parent item. [Missing image declarative-qmlintro-anchors-stretch.png] The rectangle uses anchors to define its top, left and right edges in terms of its parent item, and the bottom edge is aligned with the top of the text item. If, instead, the text item is anchored to the rectangle, which has no implicit size, the layout of the user interface will be broken because the rectangle will be assigned a zero height. PositionersPositioner items are container items that manage the positions and sizes of items in a declarative user interface. Positioners behave in a similar way to the layout managers used with standard Qt widgets, except that they are also containers in their own right. Positioners make it easier to work with many items when they need to be arranged in a regular layout. As we will see when we encounter Repeaters, it is easier to describe how items should be arranged when there are many of them than it is to try and individually position them. Standard PositionersA set of standard positioners are provided in the basic set of Qt Quick items. Since these are all based on the Item element, they contain properties that define their positions and sizes, but they do not have any visual appearance of their own; they simply arrange their child items in the space allocated to them. Any background color, if desired, must be added to a parent Rectangle.
Each of these items provides many of the same properties as the others, making it easy to exchange one with another at a later point in the design of an application or component. The common properties are spacing, add and move. As expected, the Row::spacing, Column::spacing and Grid::spacing properties have slightly different meanings because they describe how space is added to different kinds of layout. The add and move properties describe what should happen when items are added to a positioner item or moved within it. These actions are described with transitions, and will be covered later. RowRow items are used to horizontally arrange items. The following example uses a Row item to arrange three rounded Rectangle items in an area defined by an outer colored Rectangle. The spacing property is set to include a small amount of space between the rectangles.
We ensure that the parent Rectangle is large enough so that there is some space left around the edges of the horizontally centered Row item. The equally-sized rectangles in this example automatically line up because they each have the same height. Items with different heights will not be positioned vertically by the Row; these need to be lined up using anchors. Since the Row item is responsible for positioning its child items horizontally, those child items cannot use anchors to position themselves within the row. However, they can use anchors to align themselves vertically relative to one another or to the row itself. The following example uses verticalCenter anchors to vertically align three rectangles with different sizes. [Missing image declarative-qmlintro-row-anchors.png] Note that the Row item itself uses horizontalCenter and verticalCenter anchors to place itself in the center of its parent. It is free to do this because it is not being positioned by its parent, a Rectangle. However, when we place positioners inside other positioner, such as a Row inside a Column, we will need to be aware of what constraints are being imposed by the positioner's parent item. This is discussed later in this chapter. The height of the row is dependent on the heights of the individual child items and, unless specified using the height property or with anchors, it will only be as high as the tallest child item. ColumnColumn items are used to vertically arrange items. The following example uses a Column item to arrange three Rectangle items in an area defined by an outer Item. The spacing property is set to include a small amount of space between the rectangles.
In the above example, each of the rounded rectangles are positioned by the Column item. The column only changes the vertical positions of its child items and does not restrict their horizontal positions. However, the restrictions on the use of anchors do not apply to the children of these child items, so each Text item uses its centerIn anchor to horizontally and vertically align itself within its parent rectangle. The width of the column is dependent on the widths of the individual child items and, unless specified using the width property or with anchors, it will only be as wide as the widest child item. [Missing image declarative-qmlintro-column-anchors.png] The example above stretches the column horizontally to fill the entire user interface, and stretches each rectangle inside to fill the column. The text items behave as they did in the previous example. GridGrid items are used to place items in a grid or table arrangement. The following example uses a Grid item to place four Rectangle items in a 2-by-2 grid. As with the other positioners, the spacing between items can be specified using the spacing property.
There is no difference between horizontal and vertical spacing inserted between items, so any additional space must be added within the items themselves. Any empty cells in the grid must be created by defining placeholder items at the appropriate places in the grid definition. As with the Row and Column items, Grid items restrict the anchors used by their child items. Since they position items both horizontally and vertically, it is not possible to use any of the anchors to align items within the grid. However, we can use placeholder items as the grid's child items and put visible items inside those, using anchors to align them. [Missing image declarative-qmlintro-grid-positioning.png] We only show the first item, but the principle is the same for the others. FlowFlow items are used to place items like words on a page, with rows or columns of non-overlapping items. Flow items arrange items in a similar way to Grid items, with items arranged in lines along one axis (the minor axis), and lines of items placed next to each other along another axis (the major axis). The direction of flow, as well as the spacing between items, are controlled by the flow and spacing properties. The following example shows a Flow item containing a number of Text child items. These are arranged in a similar way to those shown in the screenshots.
The main differences between the Grid and Flow positioners are that items inside a Flow will wrap when they run out of space on the minor axis, and items on one line may not be aligned with items on another line if the items do not have uniform sizes. As with grid items, there is no independent control of spacing between items and between lines of items. Nesting Positioner ItemsSince each positioner is based on Item, we can nest them like other items, placing one positioner inside another. The following example shows a Column that contains two Row positioners. [Missing image declarative-qmlintro-nested-positioners.png] The example works around the restrictions on the use of anchors mentioned earlier by using appropriate anchors for each item. The innermost items, Text and Rectangle, use anchors for vertical positioning within Row items, which each perform horizontal positioning of their child items. The rows use anchors to position themselves within the Column item, which arranges them vertically. The column is centered horizontally and vertically within its parent, a non-positioning item. Strategies for UsePositioners are intended to be used in situations where it would be tedious to apply anchors to a number of items. For this reason, they are also used to position dynamically created items, such as those generated by Repeater items. The items used with positioners must have a well-defined size, otherwise positioners will not be able to determine where they should be placed, leaving their positions undefined. When using a Column, it is sufficient to give each child item a fixed height; the width can be defined using anchors. Similarly, with a Row, the width of each item should be fixed, but the height can be defined using anchors. Items used with Grid and Flow positioners should have fixed widths and heights. |
