Home · All Classes · Main Classes · Deprecated
Public Member Functions | Protected Member Functions

MLayout Class Reference

The magic layout class, extending QGraphicsLayout to add support for easily switching between multiple layout policies .This layout class uses a policy to lay out its child QGraphicsLayoutItem's. A nice feature is that transitions may be animated by use of a MLayoutAnimation. More...

Inherits QGraphicsLayout.

List of all members.

Public Member Functions

 MLayout (QGraphicsLayoutItem *parent=0)
virtual ~MLayout ()
virtual int count () const
bool isEmpty () const
virtual QGraphicsLayoutItemitemAt (int index) const
virtual void invalidate ()
QSizeF sizeHint (Qt::SizeHint which, const QSizeF &constraint=QSizeF()) const
void removeItem (const QGraphicsLayoutItem *const item)
virtual void removeAt (int index)
virtual QGraphicsLayoutItemtakeAt (int index)
virtual void animatedDeleteAt (int index)
virtual void animatedDeleteItem (const QGraphicsLayoutItem *item)
int indexOf (const QGraphicsItem *item) const
int indexOf (const QGraphicsWidget *item) const
int indexOf (const QGraphicsLayoutItem *item) const
void setPolicy (MAbstractLayoutPolicy *policy)
void setLandscapePolicy (MAbstractLayoutPolicy *policy)
MAbstractLayoutPolicylandscapePolicy () const
void setPortraitPolicy (MAbstractLayoutPolicy *policy)
MAbstractLayoutPolicyportraitPolicy () const
MAbstractLayoutPolicypolicy () const
QList< MAbstractLayoutPolicy * > registeredPolicies () const
void setAnimation (MLayoutAnimation *animation)
MLayoutAnimationanimation () const
virtual void setContentsMargins (qreal left, qreal top, qreal right, qreal bottom)
virtual void getContentsMargins (qreal *left, qreal *top, qreal *right, qreal *bottom) const
Qt::LayoutDirection layoutDirection () const

Protected Member Functions

virtual int addItem (QGraphicsLayoutItem *item)

Detailed Description

The magic layout class, extending QGraphicsLayout to add support for easily switching between multiple layout policies .

This layout class uses a policy to lay out its child QGraphicsLayoutItem's. A nice feature is that transitions may be animated by use of a MLayoutAnimation.

The MLayout owns all its associated policies, deleting them when the layout is deleted.

Relation to QGraphicsLayout

Use a MLayout if you want the ability to:

Use a QGraphicsLayout if you want:

See also:
QGraphicsLayout Example

Policies

A layout can have multiple policies, with one active at any given time. With a normal Qt layout, items are added directly to the layout, however with MLayout items are added to the layout's associated policies. The policies all inherit from QAbstractLayoutPolicy and take care of geometry management for a set of widgets. To create more complex layouts you can nest MLayouts inside each other or a mix of MLayouts and other QGraphicsLayouts.

The following code creates a MLayout with a linear and a flow policy, adding items to both policies. The first policy created will be the default policy. The other policies can be switched to by calling MAbstractLayoutPolicy::activate().

    /* Create a MLayout that we set the policies for */
    MLayout *layout = new MLayout(page.centralWidget());
    MLinearLayoutPolicy *linearPolicy = new MLinearLayoutPolicy(layout, Qt::Vertical);
    MFlowLayoutPolicy *flowPolicy = new MFlowLayoutPolicy(layout);
    for (int i = 0; i < 10; ++i) {
        MLabel *label = new MLabel(QString("Item %1").arg(i + 1));
        label->setAlignment(Qt::AlignCenter);
        label->setObjectName("item"); //Set CSS name for styling

        flowPolicy->addItem(label); // Add all of the items to the flow policy
        if (i < 3)  // But only add the first 3 items to the linear policy
            linearPolicy->addItem(label);
        else
            label->setObjectName("flowonly"); //Set CSS name, for styling flow layout items differently
    }
    /* Switch from a linear policy in landscape mode to a flow policy in portrait mode */
    layout->setLandscapePolicy(linearPolicy);
    layout->setPortraitPolicy(flowPolicy);

See also:
MLayout With Multiple Policies Example

Layouts inside Layouts

Another layout (MLayout or QGraphicsLayout) can be added to a policy to nest layouts to create more complex layouts. Items which are also layouts are not animated themselves, so prevent any problem of trying to animate a layout which is itself trying to animate the items inside of it.

Visibility

Items added to a layout will be automatically hidden and shown, depending on whether they are in the currently active policy. If your widget inherits MWidget then you can still manually hide an item by calling MWidget::hide(). Usually it is sufficient to just call mywidget->hide(), but sometimes you have a QGraphicsItem or QGraphicsLayoutItem pointer that you must first cast to a MWidget.

For example:

    /* Create a MLayout that we set the policy for */
    MLayout *layout = new MLayout;
    MLinearLayoutPolicy *policy = new MLinearLayoutPolicy(layout, Qt::Vertical);
    policy->setSpacing(10);

    /* Add 3 items to the policy, arranging them vertically stacked on top of each other */
    for (int i = 0; i < 3; ++i) {
        MLabel *label = new MLabel(QString("Item %1").arg(i + 1));
        policy->addItem(label);
        label->setObjectName("item");
        label->setAlignment(Qt::AlignCenter);
    }
    /* Hide the middle item manually.  Note that we must call the MWidget::hide() function. */
    qgraphicsitem_cast<MWidget *>(policy->itemAt(1)->graphicsItem())->hide();

    /* Attach the layout to the page */
    page.centralWidget()->setLayout(layout);
    page.appear(&window);
    window.show();

See also:
Hiding a QGraphicsLayout or MLayout

Main Policies

mlinearlayoutpolicy_small.png
mgridlayoutpolicy_small.png
mflowlayoutpolicy_small.png
mfreestylelayoutpolicy_small.png

Styling

CSS styling is done on the policies themselves - see MAbstractLayoutPolicy for more information.

See also:
CSS Styling of Policies

Writing custom widgets

For an item to be placed inside of a layout, the QGraphicsLayoutItem::sizeHint() and QGraphicsLayoutItem::sizePolicy() need to return sensible values. The minimum sizeHint should be the minimum size at which the item is usable. The preferred sizeHint should be the size at which it is usable, and the maximum sizeHint is typically QSizeF(QWIDGETSIZE_MAX, QWIDGETSIZE_MAX).

If you are implementing a custom MWidgetController and MWidgetView, then implement MWidgetView::sizeHint(), leaving the default MWidgetController::sizeHint() function which just calls the view's sizeHint function.

For an item in the layout, the QGraphicsLayoutItem::sizePolicy() function determines how the item should expand when there is space available. For example, a MButton cannot sensibly make use of more or less vertical space than its preferred height, so its vertical sizePolicy would be QSizePolicy::Fixed.

On the other hand, a text editing widget can use all the space that it can get, so its sizePolicy would be QSizePolicy::Expanding in both directions.

See also:
Laying out items in a custom policy

Examples

There are many provided examples of using layouts to help you use layouts easily and effectively.

See also:
Layout and policies, Hiding a QGraphicsLayout or MLayout, Stylish Calculator example

Constructor & Destructor Documentation

MLayout::MLayout ( QGraphicsLayoutItem parent = 0  )  [explicit]

Constructs the layout.

MLayout::~MLayout (  )  [virtual]

Destructs the layout.

This destructor deletes all policies associated with the layout.


Member Function Documentation

int MLayout::addItem ( QGraphicsLayoutItem item  )  [protected, virtual]

Internal function to add a new item to this layout.

This is called by MAbstractLayoutPolicy when an item is added to the policy.

For a user of MLayout, this function is protected. To add items to the layout, add them to the policy instead.

The layout takes ownership of the item. If item->ownedByLayout() is true, the item will be deleted when the layout is deleted.

The item will never be deleted by a removeAt() call and will always be deleted by an animatedDeleteAt() call.

If the item was already added, this returns the index of its current position.

Parameters:
item The item to add.
Returns:
Index of item whether it was added or not, or -1 if item is NULL
void MLayout::animatedDeleteAt ( int  index  )  [virtual]

Remove and delete the item at the given position.

The item is removed by the animation and then deleted. This allows for an animation when removing the item. The item is removed from the layout and all of its policies.

Note that count() will still include this item until it is deleted, but this behavior may change in future revisions. Likewise the item can still be referenced with itemAt(index) until the animation has finished.

It is currently not possible to animatedly remove an item without deleting it.

If the item is itself a layout, the layout will be deleted but the children inside will not be, and their ownership is transferred to the caller.

void MLayout::animatedDeleteItem ( const QGraphicsLayoutItem item  )  [virtual]

Remove and delete the item at the given position.

Calls animatedDeleteAt()

MLayoutAnimation * MLayout::animation (  )  const

Get the current animation.

If this is NULL then no animations will occur - all items will jump into the new states without any transitions.

Returns:
The currently set up animation.
See also:
setAnimation()
int MLayout::count (  )  const [virtual]

The number of items handled by this layout.

The count includes items currently being animatedly deleted.

void MLayout::getContentsMargins ( qreal *  left,
qreal *  top,
qreal *  right,
qreal *  bottom 
) const [virtual]

Get the contents margins for the current layout and policy.

For each of the parameters, this returns the value returned by the current policy's getContentsMargins(), unless that returns -1, in which case the value set by setContentsMargins() is used for that parameter. If neither have been set, the margins are set by the current QStyle.

For example:

 MLayout *layout = new MLayout;
 MLinearLayoutPolicy *policy = new MLinearLayoutPolicy(layout, Qt::Horizontal);
 policy->setContentsMargins(-1, 0, -1, 0);
 layout->setContentsMargins(5, 5, 5, 5);
 qreal left, top, right, bottom;
 layout->getContentsMargins(left, top, right, bottom);
 // Now left = 5, top = 0, right = 5, bottom = 0
Parameters:
left Left margin.
top Top margin.
right Right margin.
bottom Bottom margin.
See also:
setContentsMargins(), MAbstractLayoutPolicy::setContentsMargins(), MAbstractLayoutPolicy::getContentsMargins()
int MLayout::indexOf ( const QGraphicsItem item  )  const

Find the index of the given graphics item.

Parameters:
item The graphics item to find.
Returns:
The index the item is stored at or -1 if it was not found.
int MLayout::indexOf ( const QGraphicsLayoutItem item  )  const

Find the index of the given graphics layout item.

Parameters:
item The graphics layout item to find.
Returns:
The index the item is stored at or -1 if it was not found.
int MLayout::indexOf ( const QGraphicsWidget item  )  const [inline]

Find the index of the given graphics item.

Parameters:
item The graphics item to find.
Returns:
The index the item is stored at or -1 if it was not found.
void MLayout::invalidate (  )  [virtual]

Invalidate the current layout information.

This is used to trigger invalidation in the policies.

Reimplemented from QGraphicsLayout.

bool MLayout::isEmpty (  )  const

Returns if there are any items in this layout.

This includes items currently being animatedly deleted.

QGraphicsLayoutItem * MLayout::itemAt ( int  index  )  const [virtual]

Get the item at the given position.

Note that the item may be marked for deletion if animatedDeleteAt() was called.

MAbstractLayoutPolicy * MLayout::landscapePolicy (  )  const

The policy to be used in landscape mode.

The default is NULL - the policy is not changed when the device is rotated.

Qt::LayoutDirection MLayout::layoutDirection (  )  const

Returns the direction the items will be laid out in.

For example, layouts in a right-to-left language, such as Arabic or Hebrew, are usually laid out from right to left.

If the layout is in a QGraphicsWidget, the layout direction is the QGraphicsWidget::layoutDirection(). Otherwise the QApplication::layoutDirection() is used.

See also:
QGraphicsWidget::layoutDirection(), QApplication::layoutDirection(), Qt::LayoutDirection
MAbstractLayoutPolicy * MLayout::policy (  )  const

Get the currently active policy.

Returns:
The currently active policy, or NULL only if there are no associated policies.
MAbstractLayoutPolicy * MLayout::portraitPolicy (  )  const

The policy to be used in portrait mode.

The default is NULL - the policy is not changed when the device is rotated.

QList< MAbstractLayoutPolicy * > MLayout::registeredPolicies (  )  const

Get a list of all policy objects associated with this layout.

Returns:
A list of all policies associated with this layout. None of the pointers will be NULL.
void MLayout::removeAt ( int  index  )  [virtual]

Remove the item at the given position.

Removes the item immediately from the layout and all of its policies without destroying it, unless animatedDeleteAt() has been called previously for this item. Ownership of the item is transferred to the caller.

Some policies allow items to be removed for only that policy. See the appropriate policy API documentation.

Note that the item will remain on the scene, remaining visible. See the removeItem() and takeAt() functions for more information.

See also:
takeAt(), removeItem()

Reimplemented from QGraphicsLayout.

void MLayout::removeItem ( const QGraphicsLayoutItem *const   item  ) 

Remove an item handled by this layout.

Removes the item immediately from the layout and all of its policies without destroying it, unless animatedDeleteAt() has been called previously for this item. Ownership of the item is transferred to the caller.

Some policies allow items to be removed for only that policy. See the appropriate policy API documentation.

Note that the item will remain on the scene, remaining visible.

To remove the item from the layout immediately and delete it, simply do:

   delete item;

and the item will be removed automatically from the layout.

To remove the item from the layout and the scene, or to hide the item, see takeAt().

Parameters:
item The item to remove.
void MLayout::setAnimation ( MLayoutAnimation animation  ) 

Set the animation to be used for state transitions.

If animation is NULL then no animations will occur - all items will jump into the new states without any transitions.

Any previous animation is automatically deleted.

Parameters:
animation The animation to be used for all state transitions.
See also:
animation()
void MLayout::setContentsMargins ( qreal  left,
qreal  top,
qreal  right,
qreal  bottom 
) [virtual]

Set the default contents margins for the layout.

This method sets the contents margins for the layout and can be overridden by the policies.

If the current policy's getContentsMargins() returns -1 for any of the four parameters, the layout's content margins, set by this setContentsMargins() function, are used for those parameters instead.

For example:

 MLayout *layout = new MLayout;
 MLinearLayoutPolicy *policy = new MLinearLayoutPolicy(layout, Qt::Horizontal);
 policy->setContentsMargins(-1, 0, -1, 0);
 layout->setContentsMargins(5, 5, 5, 5);
 qreal left, top, right, bottom;
 layout->getContentsMargins(left, top, right, bottom);
 // Now left = 5, top = 0, right = 5, bottom = 0
Parameters:
left Left margin.
top Top margin.
right Right margin.
bottom Bottom margin.
See also:
getContentsMargins(), MAbstractLayoutPolicy::setContentsMargins(), MAbstractLayoutPolicy::getContentsMargins()

Reimplemented from QGraphicsLayout.

void MLayout::setLandscapePolicy ( MAbstractLayoutPolicy policy  ) 

Convenience function to set the policy used in landscape mode.

When the orientation of the device changes to landscape, the layout will set the given policy as active, if given.

The default is NULL - the policy is not changed when the device is rotated.

If the device is currently in landscape orientation and policy is not NULL, then the policy is immediately activated.

void MLayout::setPolicy ( MAbstractLayoutPolicy policy  ) 

Set the active policy applied to this layout.

This activates the given, already associated, policy in a layout with multiple policies.

The policy encapsulates the actual layout logic. Switching a policy triggers a relayout() of all objects handled by the layout. The first policy created for a layout is automatically made active - there's no requirement to call this function if you only have one policy for a layout.

Setting a policy that is not associated with this layout triggers an assertion.

This does nothing if policy is NULL.

This is equivalent to calling MAbstractLayoutPolicy::activate().

Parameters:
policy The policy to use for all layout operations.
void MLayout::setPortraitPolicy ( MAbstractLayoutPolicy policy  ) 

Convenience function to set the policy used in portrait mode.

When the orientation of the device changes to portrait, the layout will set the given policy as active, if given.

The default is NULL - the policy is not changed when the device is rotated.

If the device is currently in portrait orientation and policy is not NULL, then the policy is immediately activated.

QSizeF MLayout::sizeHint ( Qt::SizeHint  which,
const QSizeF constraint = QSizeF() 
) const

Get the size hints for this layout.

This just calls the sizeHint function for the current policy.

QGraphicsLayoutItem * MLayout::takeAt ( int  index  )  [virtual]

Return and remove the item at the given position.

Removes the item immediately from the layout and all of its policies without destroying it, unless animatedDeleteAt() has been called previously for this item. Ownership of the item is transferred to the caller.

Note: If animatedDeleteAt() has been called previously for this item this will return NULL.

Some policies allow items to be removed for only that policy. See the appropriate policy API documentation.

This can be used to delete all items from the layout like so:

   while(!layout->isEmpty())
       delete takeAt(0);

And it can be used to remove an item from the layout and hide it:

   if( (QGraphicsItem *item = layout->takeAt(0)->graphicsItem()) )
       item->hide;

or to remove and hide all the items:

   while(!layout->isEmpty())
       if( (QGraphicsItem *item = layout->takeAt(0)->graphicsItem()) )
           item->hide;

If you want to just remove and delete a single item, simply delete the item and it will be removed automatically from the layout.

See also:
removeItem(), removeAt()

Copyright © 2010 Nokia Corporation
MeeGo Touch