Contents

• Public Functions
• Protected Functions
• Detailed Description
• Subclassing QGraphicsLayoutItem
• Nesting QGraphicsLayoutItems

Detailed Description

TheQGraphicsLayoutItem class can be inherited to allow your custom items to be managed by layouts.

QGraphicsLayoutItem is an abstract class that defines a set of virtual functions describing sizes, size policies, and size hints for any object arranged byQGraphicsLayout. The API contains functions relevant for both the item itself and for the user of the item as most ofQGraphicsLayoutItem's functions are also part of the subclass' public API.

In most cases, existing layout-aware classes such asQGraphicsWidget andQGraphicsLayout already provide the functionality you require. However, subclassing these classes will enable you to create both graphical elements that work well with layouts (QGraphicsWidget) or custom layouts (QGraphicsLayout).

Subclassing QGraphicsLayoutItem

If you create a subclass ofQGraphicsLayoutItem and reimplement its virtual functions, you will enable the layout to resize and position your item along with other QGraphicsLayoutItems includingQGraphicsWidget andQGraphicsLayout.

You can start by reimplementing important functions: the protectedsizeHint() function, as well as the publicsetGeometry() function. If you want your items to be aware of immediate geometry changes, you can also reimplementupdateGeometry().

The geometry, size hint, and size policy affect the item's size and position. CallingsetGeometry() will always resize and reposition the item immediately. Normally, this function is called byQGraphicsLayout after the layout has been activated, but it can also be called by the item's user at any time.

ThesizeHint() function returns the item' minimum, preferred and maximum size hints. You can override these properties by callingsetMinimumSize(),setPreferredSize() orsetMaximumSize(). You can also use functions such assetMinimumWidth() orsetMaximumHeight() to set only the width or height component if desired.

TheeffectiveSizeHint() function, on the other hand, returns a size hint for any givenQt::SizeHint, and guarantees that the returned size is bound to the minimum and maximum sizes and size hints. You can set the item's vertical and horizontal size policy by callingsetSizePolicy(). ThesizePolicy property is used by the layout system to describe how this item prefers to grow or shrink.

Nesting QGraphicsLayoutItems

QGraphicsLayoutItems can be nested within other QGraphicsLayoutItems, similar to layouts that can contain sublayouts. This is done either by passing aQGraphicsLayoutItem pointer toQGraphicsLayoutItem's protected constructor, or by callingsetParentLayoutItem(). TheparentLayoutItem() function returns a pointer to the item's layoutItem parent. If the item's parent is 0 or if the parent does not inherit fromQGraphicsItem, theparentLayoutItem() function then returns 0.isLayout() returns true if theQGraphicsLayoutItem subclass is itself a layout, or false otherwise.

Qt usesQGraphicsLayoutItem to provide layout functionality in theGraphics View Framework, but in the future its use may spread throughout Qt itself.

Member Function Documentation

QGraphicsLayoutItem::QGraphicsLayoutItem(QGraphicsLayoutItem * parent = 0,bool isLayout = false)

Constructs theQGraphicsLayoutItem object.parent becomes the object's parent. IfisLayout is true the item is a layout, otherwiseisLayout is false.

[virtual]QGraphicsLayoutItem::~QGraphicsLayoutItem()

Destroys theQGraphicsLayoutItem object.

QRectF QGraphicsLayoutItem::contentsRect() const

Returns the contents rect in local coordinates.

The contents rect defines the subrectangle used by an associated layout when arranging subitems. This function is a convenience function that adjusts the item'sgeometry() by its contents margins. Note thatgetContentsMargins() is a virtual function that you can reimplement to return the item's contents margins.

See alsogetContentsMargins() andgeometry().

QSizeF QGraphicsLayoutItem::effectiveSizeHint(Qt::SizeHint which, constQSizeF & constraint = QSizeF()) const

Returns the effective size hint for thisQGraphicsLayoutItem.

which is the size hint in question.constraint is an optional argument that defines a special constrain when calculating the effective size hint. By default,constraint isQSizeF(-1, -1), which means there is no constraint to the size hint.

If you want to specify the widget's size hint for a given width or height, you can provide the fixed dimension inconstraint. This is useful for widgets that can grow only either vertically or horizontally, and need to set either their width or their height to a special value.

For example, a text paragraph item fit into a column width of 200 may grow vertically. You can passQSizeF(200, -1) as a constraint to get a suitable minimum, preferred and maximum height).

You can adjust the effective size hint by reimplementingsizeHint() in aQGraphicsLayoutItem subclass, or by calling one of the following functions:setMinimumSize(),setPreferredSize, orsetMaximumSize() (or a combination of both).

This function caches each of the size hints and guarantees thatsizeHint() will be called only once for each value ofwhich - unlessconstraint is not specified andupdateGeometry() has been called.

See alsosizeHint().

QRectF QGraphicsLayoutItem::geometry() const

Returns the item's geometry (e.g., position and size) as aQRectF. This function is equivalent toQRectF(pos(), size()).

See alsosetGeometry().

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

This virtual function provides theleft,top,right andbottom contents margins for thisQGraphicsLayoutItem. The default implementation assumes all contents margins are 0. The parameters point to values stored in qreals. If any of the pointers is 0, that value will not be updated.

See alsoQGraphicsWidget::setContentsMargins().

QGraphicsItem * QGraphicsLayoutItem::graphicsItem() const

Returns theQGraphicsItem that this layout item represents. ForQGraphicsWidget it will return itself. For custom items it can return an aggregated value.

See alsosetGraphicsItem().

bool QGraphicsLayoutItem::isLayout() const

Returns true if thisQGraphicsLayoutItem is a layout (e.g., is inherited by an object that arranges otherQGraphicsLayoutItem objects); otherwise returns false.

See alsoQGraphicsLayout.

qreal QGraphicsLayoutItem::maximumHeight() const

Returns the maximum height.

See alsosetMaximumHeight(),setMaximumSize(), andmaximumSize().

QSizeF QGraphicsLayoutItem::maximumSize() const

Returns the maximum size.

See alsosetMaximumSize(),minimumSize(),preferredSize(),Qt::MaximumSize, andsizeHint().

qreal QGraphicsLayoutItem::maximumWidth() const

Returns the maximum width.

See alsosetMaximumWidth(),setMaximumSize(), andmaximumSize().

qreal QGraphicsLayoutItem::minimumHeight() const

Returns the minimum height.

See alsosetMinimumHeight(),setMinimumSize(), andminimumSize().

QSizeF QGraphicsLayoutItem::minimumSize() const

Returns the minimum size.

See alsosetMinimumSize(),preferredSize(),maximumSize(),Qt::MinimumSize, andsizeHint().

qreal QGraphicsLayoutItem::minimumWidth() const

Returns the minimum width.

See alsosetMinimumWidth(),setMinimumSize(), andminimumSize().

bool QGraphicsLayoutItem::ownedByLayout() const

Returns whether a layout should delete this item in its destructor. If its true, then the layout will delete it. If its false, then it is assumed that another object has the ownership of it, and the layout won't delete this item.

If the item inherits bothQGraphicsItem andQGraphicsLayoutItem (such asQGraphicsWidget does) the item is really part of two ownership hierarchies. This property informs what the layout should do with its child items when it is destructed. In the case ofQGraphicsWidget, it is preferred that when the layout is deleted it won't delete its children (since they are also part of the graphics item hierarchy).

By default this value is initialized to false inQGraphicsLayoutItem, but it is overridden byQGraphicsLayout to return true. This is becauseQGraphicsLayout is not normally part of theQGraphicsItem hierarchy, so the parent layout should delete it. Subclasses might override this default behaviour by callingsetOwnedByLayout(true).

This function was introduced in Qt 4.6.

See alsosetOwnedByLayout().

QGraphicsLayoutItem * QGraphicsLayoutItem::parentLayoutItem() const

Returns the parent of thisQGraphicsLayoutItem, or 0 if there is no parent, or if the parent does not inherit fromQGraphicsLayoutItem (QGraphicsLayoutItem is often used through multiple inheritance withQObject-derived classes).

See alsosetParentLayoutItem().

qreal QGraphicsLayoutItem::preferredHeight() const

Returns the preferred height.

See alsosetPreferredHeight(),setPreferredSize(), andpreferredSize().

QSizeF QGraphicsLayoutItem::preferredSize() const

Returns the preferred size.

See alsosetPreferredSize(),minimumSize(),maximumSize(),Qt::PreferredSize, andsizeHint().

qreal QGraphicsLayoutItem::preferredWidth() const

Returns the preferred width.

See alsosetPreferredWidth(),setPreferredSize(), andpreferredSize().

[virtual]void QGraphicsLayoutItem::setGeometry(constQRectF & rect)

This virtual function sets the geometry of theQGraphicsLayoutItem torect, which is in parent coordinates (e.g., the top-left corner ofrect is equivalent to the item's position in parent coordinates).

You must reimplement this function in a subclass ofQGraphicsLayoutItem to receive geometry updates. The layout will call this function when it does a rearrangement.

Ifrect is outside of the bounds ofminimumSize andmaximumSize, it will be adjusted to its closest size so that it is within the legal bounds.

See alsogeometry().

[protected]void QGraphicsLayoutItem::setGraphicsItem(QGraphicsItem * item)

If theQGraphicsLayoutItem represents aQGraphicsItem, and it wants to take advantage of the automatic reparenting capabilities ofQGraphicsLayout it should set this value. Note that if you deleteitem and not delete the layout item, you are responsible of calling setGraphicsItem(0) in order to avoid having a dangling pointer.

See alsographicsItem().

void QGraphicsLayoutItem::setMaximumHeight(qreal height)

Sets the maximum height toheight.

See alsomaximumHeight(),setMaximumSize(), andmaximumSize().

void QGraphicsLayoutItem::setMaximumSize(constQSizeF & size)

Sets the maximum size tosize. This property overridessizeHint() forQt::MaximumSize and ensures thateffectiveSizeHint() will never return a size larger thansize. In order to unset the maximum size, use an invalid size.

See alsomaximumSize(),minimumSize(),preferredSize(),Qt::MaximumSize, andsizeHint().

void QGraphicsLayoutItem::setMaximumSize(qreal w,qreal h)

This convenience function is equivalent to callingsetMaximumSize(QSizeF(w,h)).

See alsomaximumSize(),setMinimumSize(),setPreferredSize(), andsizeHint().

void QGraphicsLayoutItem::setMaximumWidth(qreal width)

Sets the maximum width towidth.

See alsomaximumWidth(),setMaximumSize(), andmaximumSize().

void QGraphicsLayoutItem::setMinimumHeight(qreal height)

Sets the minimum height toheight.

See alsominimumHeight(),setMinimumSize(), andminimumSize().

void QGraphicsLayoutItem::setMinimumSize(constQSizeF & size)

Sets the minimum size tosize. This property overridessizeHint() forQt::MinimumSize and ensures thateffectiveSizeHint() will never return a size smaller thansize. In order to unset the minimum size, use an invalid size.

See alsominimumSize(),maximumSize(),preferredSize(),Qt::MinimumSize,sizeHint(),setMinimumWidth(), andsetMinimumHeight().

void QGraphicsLayoutItem::setMinimumSize(qreal w,qreal h)

This convenience function is equivalent to callingsetMinimumSize(QSizeF(w,h)).

See alsominimumSize(),setMaximumSize(),setPreferredSize(), andsizeHint().

void QGraphicsLayoutItem::setMinimumWidth(qreal width)

Sets the minimum width towidth.

See alsominimumWidth(),setMinimumSize(), andminimumSize().

[protected]void QGraphicsLayoutItem::setOwnedByLayout(bool ownership)

Sets whether a layout should delete this item in its destructor or not.ownership must be true to in order for the layout to delete it.

This function was introduced in Qt 4.6.

See alsoownedByLayout().

void QGraphicsLayoutItem::setParentLayoutItem(QGraphicsLayoutItem * parent)

Sets the parent of thisQGraphicsLayoutItem toparent.

See alsoparentLayoutItem().

void QGraphicsLayoutItem::setPreferredHeight(qreal height)

Sets the preferred height toheight.

See alsopreferredHeight(),preferredWidth(),setPreferredSize(), andpreferredSize().

void QGraphicsLayoutItem::setPreferredSize(constQSizeF & size)

Sets the preferred size tosize. This property overridessizeHint() forQt::PreferredSize and provides the default value foreffectiveSizeHint(). In order to unset the preferred size, use an invalid size.

See alsopreferredSize(),minimumSize(),maximumSize(),Qt::PreferredSize, andsizeHint().

void QGraphicsLayoutItem::setPreferredSize(qreal w,qreal h)

This convenience function is equivalent to callingsetPreferredSize(QSizeF(w,h)).

See alsopreferredSize(),setMaximumSize(),setMinimumSize(), andsizeHint().

void QGraphicsLayoutItem::setPreferredWidth(qreal width)

Sets the preferred width towidth.

See alsopreferredWidth(),preferredHeight(),setPreferredSize(), andpreferredSize().

void QGraphicsLayoutItem::setSizePolicy(constQSizePolicy & policy)

Sets the size policy topolicy. The size policy describes how the item should grow horizontally and vertically when arranged in a layout.

QGraphicsLayoutItem's default size policy is (QSizePolicy::Fixed,QSizePolicy::Fixed,QSizePolicy::DefaultType), but it is common for subclasses to change the default. For example,QGraphicsWidget defaults to (QSizePolicy::Preferred,QSizePolicy::Preferred,QSizePolicy::DefaultType).

See alsosizePolicy() andQWidget::sizePolicy().

void QGraphicsLayoutItem::setSizePolicy(QSizePolicy::Policy hPolicy,QSizePolicy::Policy vPolicy,QSizePolicy::ControlType controlType = QSizePolicy::DefaultType)

This is an overloaded function.

This function is equivalent to callingsetSizePolicy(QSizePolicy(hPolicy,vPolicy,controlType)).

See alsosizePolicy() andQWidget::sizePolicy().

[pure virtual protected]QSizeF QGraphicsLayoutItem::sizeHint(Qt::SizeHint which, constQSizeF & constraint = QSizeF()) const

This pure virtual function returns the size hint forwhich of theQGraphicsLayoutItem, using the width or height ofconstraint to constrain the output.

Reimplement this function in a subclass ofQGraphicsLayoutItem to provide the necessary size hints for your items.

See alsoeffectiveSizeHint().

QSizePolicy QGraphicsLayoutItem::sizePolicy() const

Returns the current size policy.

See alsosetSizePolicy() andQWidget::sizePolicy().

[virtual]void QGraphicsLayoutItem::updateGeometry()

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

See alsoeffectiveSizeHint().