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

MAbstractLayoutPolicy Class Reference

The MAbstractLayoutPolicy class provides the base class for all MLayout policies.MAbstractLayoutPolicy is an abstract class that defines an API for arranging QGraphicsWidget, MWidget and other QGraphicsLayoutItem objects in the associated MLayout. More...

Inherited by MFlowLayoutPolicy, MFreestyleLayoutPolicy, MGridLayoutPolicy, and MLinearLayoutPolicy.

List of all members.

Public Member Functions

 MAbstractLayoutPolicy (MLayout *layout)
virtual ~MAbstractLayoutPolicy ()
void setContentsMargins (qreal left, qreal top, qreal right, qreal bottom)
void unsetContentsMargins ()
void getContentsMargins (qreal *left, qreal *top, qreal *right, qreal *bottom) const
MLayoutlayout () const
void activate ()
bool isActive () const
virtual QSizeF sizeHint (Qt::SizeHint which, const QSizeF &constraint=QSizeF()) const =0
void updateStyle ()
void setStyleName (const QString &name)
QString styleName () const
void setObjectName (const QString &name)
QString objectName () const
virtual void setHorizontalSpacing (qreal spacing)
virtual qreal horizontalSpacing () const
virtual void setVerticalSpacing (qreal spacing)
virtual qreal verticalSpacing () const
virtual void setSpacing (qreal spacing)
virtual int count () const
virtual QGraphicsLayoutItemitemAt (int index) const
int indexOf (const QGraphicsLayoutItem *item) const
virtual void removeAt (int index)
void removeItem (const QGraphicsLayoutItem *item)
virtual bool hasHeightForWidth () const

Protected Member Functions

 MAbstractLayoutPolicy (MAbstractLayoutPolicyPrivate &)
void setHeightForWidth (bool hasHeightForWidth)
virtual void insertItem (int index, QGraphicsLayoutItem *item)
virtual void addItem (QGraphicsLayoutItem *item)
void setItemGeometry (int index, const QRectF &geometry)
QRectF itemGeometry (int index) const
void hideItem (int index)
virtual void applyStyle ()
const MAbstractLayoutPolicyStylestyle () const
virtual void relayout ()=0
virtual void Q_DECL_DEPRECATED aboutToBeRemovedFromLayout (const QGraphicsLayoutItem *item)
void invalidatePolicyAndLayout ()
virtual void invalidate ()
virtual void updateGeometry ()
QRectF contentsArea () const
virtual void activated ()

Protected Attributes

MAbstractLayoutPolicyPrivate *const d_ptr

Detailed Description

The MAbstractLayoutPolicy class provides the base class for all MLayout policies.

MAbstractLayoutPolicy is an abstract class that defines an API for arranging QGraphicsWidget, MWidget and other QGraphicsLayoutItem objects in the associated MLayout.

A MLayout can have many different policies, with one of the policies being active at any moment. Changing a MLayout's active policy causes the items to move into a new position.

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().

Multiple Policies

A layout can have multiple policies associated with it. See the MLayout documentation for more information and examples.

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

CSS Styling of Policies

Policies can be styled in the CSS stylesheet files, however the class name is always MAbstractLayoutPolicy. Their object name can be set with setStyleName() and they can be styled different depending on the current device orientation.

For example:

  MLinearLayoutPolicy mypolicy(mylayout);
  mypolicy.setStyleName("address");

could then be styled in the .css file with

  MAbstractLayoutPolicyStyle#address {
    vertical-spacing: 5;
    horizontal-spacing: 5;
    margin-left: 10.0;
    margin-right: 10.0;
    margin-top: 10.0;
    margin-bottom: 10.0;
  }
  MAbstractLayoutPolicyStyle#address.Landscape {
    vertical-spacing: 0;
  }

This sets the vertical spacing to be 0 pixels in landscape mode, and 5 pixels in portrait mode.

Writing a Custom Policy

Implementing new layout policies is a straight forward process. This abstract base class handles registration and deregistration with the layout it is associated with, and by default handles the adding and removing of items from the policy.

FunctionDescription
MAbstractLayoutPolicy::addItem() Add an item to the layout. The default implementation is usually sufficient (adds the item to the internal list of items, and invalidates the policy and layout). You may want to implement custom addItem functions that additionally take position, alignment etc parameters. You must call MAbstractLayoutPolicy::addItem() from any addItem implementation to maintain the internal state.
MAbstractLayoutPolicy::relayout() Triggers a relayout of items. This does the main task of laying out the items.
MAbstractLayoutPolicy::sizeHint() Returns the policy's size hints. This must enclose all of the items inside

Additionally it may be useful to implement the following functions if the default behaviour is not sufficient:

FunctionDescription
MAbstractLayoutPolicy::setHorizontalSpacing() Sets the horizontal spacing between items.
MAbstractLayoutPolicy::setVerticalSpacing() Sets the vertical spacing between items.
MAbstractLayoutPolicy::sizeHint() Returns the policy's size hints.
MAbstractLayoutPolicy::count() Returns the number of items in your layout.
MAbstractLayoutPolicy::itemAt() Returns a pointer to an item in your layout.
MAbstractLayoutPolicy::removeAt() Removes an item from your layout without destroying it.
MAbstractLayoutPolicy::invalidate() Notifies that an item has been added/removed or some other property has changed, requiring items to be laid out. You may want to override this to invalidate an internal model.

For more details on how to implement each function, refer to the individual function documentation.

Each layout defines its own API for arranging widgets and layout items. For example, with a grid layout, you require a row and a column index with optional row and column spans, alignment, spacing, and more. A linear layout, however, requires a single row or column index to position its items. For a grid layout, the order of insertion does not affect the layout in any way, but for a linear layout, the order is essential. When writing your own layout subclass, you are free to choose the API that best suits your layout.

Laying out items in a custom policy

For each item in a policy, the policy should at least call the QGraphicsLayoutItem::preferredSize() function to get the item's preferred size. A well-behaved policy will also respect the QGraphicsLayoutItem::sizePolicy() so that items can expand to take up all available space.


Constructor & Destructor Documentation

MAbstractLayoutPolicy::MAbstractLayoutPolicy ( MLayout layout  )  [explicit]

Create a policy and associate it with the given layout.

The layout must not be NULL. The layout takes ownership of the policy, deleting the policy when the layout is deleted. If the policy is explicitly deleted, it will automatically be removed from the layout.

MAbstractLayoutPolicy::~MAbstractLayoutPolicy (  )  [virtual]

Destroys an abstract layout policy.

If the policy was currently active, the next policy in the layout is automatically activated, if available. Items in this policy continue to be owned by the associated MLayout and are hidden if not in the new policy.

See also:
activate()
MAbstractLayoutPolicy::MAbstractLayoutPolicy ( MAbstractLayoutPolicyPrivate &  p  )  [explicit, protected]

Shared d_ptr setup constructor.


Member Function Documentation

void MAbstractLayoutPolicy::aboutToBeRemovedFromLayout ( const QGraphicsLayoutItem item  )  [protected, virtual]
Deprecated:
Use removeAt() instead. There shouldn't be any need for this function. Since 0.19
void MAbstractLayoutPolicy::activate (  ) 

Make this policy the active one.

This method sets the policy as the one used by the layout to do all the work.

void MAbstractLayoutPolicy::activated (  )  [protected, virtual]

Called by the layout when the policy is made active.

The base class implementation hides all the items not in this policy, and shows all items that are in this policy.

void MAbstractLayoutPolicy::addItem ( QGraphicsLayoutItem item  )  [protected, virtual]

Add an item to the policy.

If the item is a QGraphicsWidget, it will be shown or hidden depending on whether it is in the active policy.

Note that the order of the items in the policy is independent of the order of the items in the MLayout.

Parameters:
item The item to add.
See also:
Hiding a QGraphicsLayout or MLayout

Reimplemented in MFreestyleLayoutPolicy, and MLinearLayoutPolicy.

void MAbstractLayoutPolicy::applyStyle (  )  [protected, virtual]

Called when the style has changed (e.g the CSS file has been loaded).

Inheriting policies reimplementing this should call this base class function. This function can be reimplemented to be read specific attributes in the CSS file. The pointer to the style, containing the updated values, can be accessed via the style() function

See also:
style()
QRectF MAbstractLayoutPolicy::contentsArea (  )  const [protected]

Get the current content rectangle of the layout.

Be aware that these coordinates are not local, this is different to contentsRect()

int MAbstractLayoutPolicy::count (  )  const [virtual]

Returns the number of items in the policy.

void MAbstractLayoutPolicy::getContentsMargins ( qreal *  left,
qreal *  top,
qreal *  right,
qreal *  bottom 
) const

Get the content margins override for this policy.

This method gets the contents margins override for the policy.

By default, these are all -1, meaning that the MLayout's getContentsMargins will be used. Any that are changed to be a non-negative number will override the value returned by MLayout's getContentsMargins

Parameters:
left Left margin. -1 indicates to use MLayout's left margin
top Top margin. -1 indicates to use MLayout's top margin
right Right margin. -1 indicates to use MLayout's right margin
bottom Bottom margin. -1 indicates to use MLayout's bottom margin
bool MAbstractLayoutPolicy::hasHeightForWidth (  )  const [virtual]

Returns whether this policy's height depends on its width even if it does not contain any height-for-width items.

void MAbstractLayoutPolicy::hideItem ( int  index  )  [protected]

Hide the given item.

When a policy is made active, any items not in the policy are automatically hidden. The rest of the items in the policy are not changed. To hide any items that are in the policy, call this function.

To show the item again call the setItemGeometry() function.

To hide items as a user of MLayout, see Visibility

qreal MAbstractLayoutPolicy::horizontalSpacing (  )  const [virtual]

Get the horizontal spacing.

Returns:
The spacing to use.
int MAbstractLayoutPolicy::indexOf ( const QGraphicsLayoutItem item  )  const

Index of the given item.

This function uses the virtual functions count() and itemAt() to find the index of the given item.

Note that this takes linear, O(N), time.

Parameters:
item The item to return the index of
Returns:
Index of the item
void MAbstractLayoutPolicy::insertItem ( int  index,
QGraphicsLayoutItem item 
) [protected, virtual]

Insert an item in the policy at the given index.

Inserts item into the layout at index, or before any item that is currently at index.

The base class function is protected since this does not make sense for all policies. Policies can make this function public where it is suitable, or create their own API.

Parameters:
item The item to insert.
index The index to place the item

Reimplemented in MLinearLayoutPolicy.

void MAbstractLayoutPolicy::invalidate (  )  [protected, virtual]

Invalidate any cached size and geometry information here. This is called whenever the layout itself is invalidated by MLayout, and also called by invalidatePolicyAndLayout().

void MAbstractLayoutPolicy::invalidatePolicyAndLayout (  )  [protected]

Invalidate any cached size and geometry information here and invalidate layout If this policy is the current policy (aka activated) then it invalidates the layout. It then calls invalidate() which can be overridden by base classes to invalidate internal models.

bool MAbstractLayoutPolicy::isActive (  )  const

Whether this is the active policy.

Checks whether this policy is the one currently used by the associated layout.

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

Get the item stored in the policy.

Get the item found at the given index.

Parameters:
index The index to check.
Returns:
The item at the given index or NULL if the index is invalid.
QRectF MAbstractLayoutPolicy::itemGeometry ( int  index  )  const [protected]

Return the target geometry of the item at the given index.

MLayout * MAbstractLayoutPolicy::layout (  )  const

Get the layout this policy is associated with.

QString MAbstractLayoutPolicy::objectName (  )  const

returns the style name.

Deprecated:
Use styleName() instead. It simply calls styleName().
virtual void MAbstractLayoutPolicy::relayout (  )  [protected, pure virtual]

Callback triggered when a relayout is required.

This method is triggered whenever complete relayout is required (e.g. when the layout itself is resized).

All affected items are computed and the layout is triggered to update the information.

You must override this method in your custom policies.

Implemented in MFreestyleLayoutPolicy.

void MAbstractLayoutPolicy::removeAt ( int  index  )  [virtual]

Remove an item from the policy only.

Remove an item from the policy, leaving it in layout. If the policy is active and the item is a QGraphicsWidget (or MWidget) then the item will be hidden via QGraphicsWidget::hide().

Note that layouts themselves are not a QGraphicsWidget and so will not be hidden when removed from another layout. So if you remove another layout from a policy, it will stay on the screen. You can solve this by placing the layout inside of a widget, and put that widget in the policy.

Parameters:
index The policy index of the item to remove.
void MAbstractLayoutPolicy::removeItem ( const QGraphicsLayoutItem item  ) 

Remove an item from the policy only.

Convienence function

Parameters:
item The item to remove.
void MAbstractLayoutPolicy::setContentsMargins ( qreal  left,
qreal  top,
qreal  right,
qreal  bottom 
)

Set the content margins for this policy.

This method sets the contents margins for the policy, overriding the values set in the CSS.

By default, these are all -1, meaning that the MLayout::getContentsMargins() will be used. Any that are changed to be a non-negative number will override the value returned by MLayout::getContentsMargins()

Parameters:
left Left margin. Set to -1 indicate to use MLayout's left margin
top Top margin. Set to -1 indicate to use MLayout's top margin
right Right margin. Set to -1 indicate to use MLayout's right margin
bottom Bottom margin. Set to -1 indicate to use MLayout's bottom margin

To use the values set in the CSS again, call unsetContentsMargins();

See also:
MLayout::getContentsMargins()
MLayout::setContentsMargins()
unsetContentsMargins()
getContentsMargins()
void MAbstractLayoutPolicy::setHeightForWidth ( bool  hasHeightForWidth  )  [protected]

Set whether this policy has a height which depends on its width.

void MAbstractLayoutPolicy::setHorizontalSpacing ( qreal  spacing  )  [virtual]

Set the horizontal spacing.

The base implementation sets the horizontal spacing and invalidates the policy, triggering a relayout(). This overrides the value set in the CSS.

Parameters:
spacing The spacing to use.
void MAbstractLayoutPolicy::setItemGeometry ( int  index,
const QRectF geometry 
) [protected]

Set the target geometry of the given item to the given geometry.

To be used by inherited policies to set the geometry of the item. Typically called from relayout() and addItem(). This does nothing if the policy is not the currently active policy in the layout.

Note that this causes the item to be shown, if it's being hidden.

void MAbstractLayoutPolicy::setObjectName ( const QString name  ) 

Sets the style name.

Deprecated:
Use setStyleName() instead. It simply calls setStyleName().
void MAbstractLayoutPolicy::setSpacing ( qreal  spacing  )  [virtual]

Convenience function to set both the horizontal and vertical spacing.

Reimplemented in MLinearLayoutPolicy.

void MAbstractLayoutPolicy::setStyleName ( const QString name  ) 

Sets the name of this policy, for CSS styling.

This is similar to MWidgetController::setStyleName() and is used as the object name for the MStyle object name. For example:

  MLinearLayoutPolicy mypolicy(mylayout);
  mypolicy.setStyleName("address");

could then be styled in the .css file with

  MAbstractLayoutPolicy#address {
    vertical-spacing: 5;
  }

By default the object's name is the empty string.

Parameters:
name object name
void MAbstractLayoutPolicy::setVerticalSpacing ( qreal  spacing  )  [virtual]

Set the vertical spacing.

The base implementation sets the horizontal spacing and invalidates the policy, triggering a relayout(). This overrides the value set in the CSS.

Parameters:
spacing The spacing to use.
virtual QSizeF MAbstractLayoutPolicy::sizeHint ( Qt::SizeHint  which,
const QSizeF constraint = QSizeF() 
) const [pure virtual]

Return the sizeHint for this policy.

Implementations must ensure that the sizeHint returned encompasses all of the items inside, including taking into account contents margins returned from getContentsMargins()

External classes, except for MLayout, should not call this directly, but should use MLayout::effectiveSizeHint()

const MAbstractLayoutPolicyStyle * MAbstractLayoutPolicy::style (  )  const [protected]

Return the style for this policy.

QString MAbstractLayoutPolicy::styleName (  )  const

Return the name of this policy, for CSS styling.

This is similar in functionality and usage to MWidgetController::styleName()

See also:
setStyleName(const QString &)
void MAbstractLayoutPolicy::unsetContentsMargins (  ) 

Unset the contents margins for this policy, reading the values set in the CSS instead.

void MAbstractLayoutPolicy::updateGeometry (  )  [protected, virtual]

This virtual function discards any cached size hint information. You should always call this function if you change the return value of the sizeHint() function. Subclasses must always call the base implementation when reimplementing this function.

void MAbstractLayoutPolicy::updateStyle (  ) 

Called when the style has been changed.

See also:
applyStyle()
qreal MAbstractLayoutPolicy::verticalSpacing (  )  const [virtual]

Get the vertical spacing.

Returns:
The spacing to use.

Member Data Documentation

MAbstractLayoutPolicyPrivate* const MAbstractLayoutPolicy::d_ptr [protected]

Copyright © 2010 Nokia Corporation
MeeGo Touch