MeeGo Touch: Layout and Policies

Basics

MeeGo Touch includes a set of layout management classes that are used to describe how widgets are laid out in an application's user interface. These layouts automatically position and resize widgets when the amount of space available for them changes, ensuring that they are consistently arranged and that the user interface as a whole remains usable.

There are two different sets of layout classes.

The first is provided by Qt, and inherit from QGraphicsLayout, including QGraphicsLinearLayout, QGraphicsGridLayout, etc. These Qt classes provide an easy way to layout items as you want.

The second set of layout classes is provided by MeeGo Touch, and offer additional feature, at the cost of slightly more overhead. The MeeGo Touch classes work in a slightly different way - there is a single MLayout to which you can add one or more policies that inherit MAbstractLayoutPolicy. This allows a single layout to have multiple policies, with one active at a given time. A different policy can be made active at any time, causing the items within the layout to move into their new position.

The multiple policies in a single MLayout do not even need to contain the same items. New items will be shown and hidden as necessary (Unless the item is itself a layout, since a layout cannot be directly hidden itself, but a layout inside of a widget inside of a layout will be hidden. See Hiding a QGraphicsLayout or MLayout).

Tips for Using Layouts

When you use a layout or layout policy, you do not need to pass a parent when constructing the child widgets. The layout will automatically reparent the widgets so that they are children of the widget on which the layout is installed. When the parent widget is deleted, its layout and all of its children are also deleted.

Widgets in a layout are children of the widget on which the layout is installed, not of the layout itself. Widgets can only have other widgets as parent, not layouts. You can nest layouts using addLayout() on a layout; the inner layout then becomes a child of the layout it is inserted into.

You can have one policy when in landscape mode and another policy when portrait mode. You do not even need to have the same items in each case.

If you only want to switch between a horizontal and vertical linear layout policy, you can use MLinearLayoutPolicy::setOrientation() instead of multiple policies.

For a complex set of nested layouts it is easier and more lightweight to use nested QGraphicsLayouts than to try to nest MLayouts .

See the QLayout and QGraphicsLayout documentation for more information and tips, and see the examples.

Right-to-left

In right-to-left languages, such as arabic, the layouts are automatically reversed. This is usually the correct behavior, however you can override this by directly calling QGraphicsWidget::setLayoutDirection(). For example the calculator example has the following code snippet:

CalculatorWidget::CalculatorWidget()
{
    mValue = 0;

    //Prevent the layout from changing in right-to-left.
    //The calculation line will still be reversed however.
    setLayoutDirection(Qt::LeftToRight);

    /* Create a MLayout attached to this widget */
    MLayout *layout = new MLayout(this);

Widget Sizes

To determine the size of a widget in a layout, the layout uses the widget's QGraphicsLayoutItem::preferredSize() and its QGraphicsLayoutItem::sizePolicy() functions. The preferred size of a MWidgetController is determined from:

The constraint passed to the MWidgetController::sizeHint() function - usually due to the layout.
Developer set hints (using QGraphicsLayoutItem::setPreferredSize(), etc).
Style set size (e.g. from the CSS files).
View's MWidgetView::sizeHint() function.
MWidgetController::layout()->QGraphicsLayoutItem::sizeHint() function.

The sizes given from the first 3 steps are combined, in the order of preference as shown. If the height and/or width is not specified, then the MWidgetView::sizeHint() function is called, with constraint parameter set to the size determined so far. The result from the view is then combined with the constraint.

Finally, if this size is still not valid, the size is combined with QGraphicsWidget::sizeHint() which in turn uses the layout's QGraphicsLayoutItem::sizeHint() function.

If you create your widget and its width depends on its height, then its size policy must have set QSizePolicy::hasHeightForWidth().

See also:: MWidgetView::sizeHint()

Main Policies

MLinearLayoutPolicy - For placing items horizontally or vertically:

MGridLayoutPolicy - For placing items in a grid:

MFlowLayoutPolicy - For placing items in a horizontal line, overflowing onto the next line:

MFreestyleLayoutPolicy - For placing items freely, but still preventing items from overlapping:

Multiple Policies

Multiple policies can be assigned to a layout. This is particularly useful to have one policy when in portrait mode and another when in landscape mode. For example:

A more concrete example is given with the example calculator program.

See also:: MLayout With Multiple Policies Example, Stylish Calculator example, Hiding a QGraphicsLayout or MLayout, MLayout

More complex layouting using QGraphicsLayout

For a more complex layout of items, you can place multiple layouts together. This is easiest using a mix of MLayouts and QGraphicsLayout, using a MLayout only when animations and multiple policies are required.

For example using multiple QGraphicsLinearLayouts we can obtain a layout where items are laid in rows, but the items do not line up vertically. For example:

See also:: QGraphicsLinearLayout example, QGraphicsGridLayout example, QGraphicsLayout Example

Layout and Policies