Home · All Classes · Main Classes · Deprecated |
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.
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 |
MLayout * | layout () 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 QGraphicsLayoutItem * | itemAt (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 MAbstractLayoutPolicyStyle * | style () 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 |
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.
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().
A layout can have multiple policies associated with it. See the MLayout documentation for more information and examples.
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.
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.
Function | Description |
---|---|
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:
Function | Description |
---|---|
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.
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.
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.
MAbstractLayoutPolicy::MAbstractLayoutPolicy | ( | MAbstractLayoutPolicyPrivate & | p | ) | [explicit, protected] |
Shared d_ptr setup constructor.
void MAbstractLayoutPolicy::aboutToBeRemovedFromLayout | ( | const QGraphicsLayoutItem * | item | ) | [protected, virtual] |
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.
item | The item to add. |
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
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
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.
int MAbstractLayoutPolicy::indexOf | ( | const QGraphicsLayoutItem * | item | ) | const |
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.
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.
index | The index to check. |
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.
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.
index | The policy index of the item to remove. |
void MAbstractLayoutPolicy::removeItem | ( | const QGraphicsLayoutItem * | item | ) |
Remove an item from the policy only.
Convienence function
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()
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();
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.
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.
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.
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.
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()
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.
qreal MAbstractLayoutPolicy::verticalSpacing | ( | ) | const [virtual] |
Get the vertical spacing.
MAbstractLayoutPolicyPrivate* const MAbstractLayoutPolicy::d_ptr [protected] |
Copyright © 2010 Nokia Corporation | MeeGo Touch |