Home · All Classes · Main Classes · Grouped Classes · Modules · Functions

QGraphicsLayoutItem Class Reference
[
QtGui module]

The QGraphicsLayoutItem class can be inherited to make your custom items layout-aware. More...

 #include <QGraphicsLayoutItem>

Inherited by QGraphicsLayout and QGraphicsWidget.

This class was introduced in Qt 4.4.

Public Functions

Protected Functions


Detailed Description

The QGraphicsLayoutItem class can be inherited to make your custom items layout-aware.

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

By creating a subclass of QGraphicsLayoutItem (e.g., directly or with multiple inheritance), and reimplementing its virtual functions, you will enable the layout to resize and position your item together with other QGraphicsLayoutItem items (including QGraphicsWidget and QGraphicsLayout itself). You can start by reimplementing the most important functions: the protected sizeHint() function, and the public geometry() and setGeometry() functions. If you want your items to become aware of immediate geometry changes, you can also reimplement updateGeometry().

The geometry, size hint, and size policy affect the item's size and position. Calling setGeometry() will always resize and reposition the item immediately; this function is normally called by QGraphicsLayout after the layout has been activated, but can also be called by the item's user at any time. sizeHint() returns the item' minimum, preferred and maximum size 4 hints. You can override these properties by calling setMinimumSize(), setPreferredSize() or setMaximumSize(). The public effectiveSizeHint() function returns a size hint for any given Qt::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 calling setSizePolicy(); this property is used by the layout system and describes how this item prefers to grow or shrink.

You can stack QGraphicsLayoutItem items inside others by either passing a QGraphicsLayoutItem pointer to QGraphicsLayoutItem's protected constructor, or by calling setParentLayoutItem(). This is how you "nest" layoutItem items, just like layouts that can contain other sublayouts. The parentLayoutItem() function returns a pointer to the item's layoutItem parent, or 0 if the item's parent is either 0, or if the item's parent does not inherit from QGraphicsLayoutItem. isLayout() returns true if the QGraphicsLayoutItem subclass is itself a layout, or false otherwise.

Most of the time, you will not need to worry about this class; existing layout-aware classes such as QGraphicsWidget and QGraphicsLayout already provide the functionality you need, and by subclassing these classes instead, you can easily create both layout-aware graphical elements (QGraphicsWidget), or custom layouts (QGraphicsLayout).

Qt uses QGraphicsLayoutItem for providing layout functionality in the The Graphics View Framework, but in the future its use may spread throughout Qt itself.

See also QGraphicsWidget, QGraphicsLayout, QGraphicsLinearLayout, and QGraphicsGridLayout.


Member Function Documentation

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

Constructs the QGraphicsLayoutItem object. parent becomes the object's parent, and if isLayout is true the item is a layout, otherwise isLayout is false.

QGraphicsLayoutItem::~QGraphicsLayoutItem ()   [virtual]

Destroys the QGraphicsLayoutItem 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's geometry() by its contents margins. Note that getContentsMargins() is a virtual function that you can reimplement to return the item's contents margins.

See also getContentsMargins() and geometry().

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

Returns the effective size hint for this QGraphicsLayoutItem. 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 is QSizeF(-1, -1), which means there is no constraint to the size hint.

If you want the widget's size hint for a given width or height, you can provide the fixated dimension in constraint. This is useful for widgets that can grow only either vertically or horizontally, and need to fix either their width or their height to a special value (e.g., if a text paragraph item must fit into a column width of 200 may grow vertically, you can pass QSizeF(200, -1) as a constraint to get a suitable minimum, preferred and maximum height).

You can affect the effective size hint by either reimplementing sizeHint() in a QGraphicsLayoutItem subclass, or by calling one of setMinimumSize(), setPreferredSize() or setMaximumSize() (or a combination of both).

This function caches each of the size hints, and guarantees that unless updateGeometry() has been called, and as long as constraint is unused, sizeHint() will only be called once for each value of which.

See also sizeHint().

QRectF QGraphicsLayoutItem::geometry () const   [pure virtual]

This pure virtual function returns the geometry of the QGraphicsLayoutItem as a QRectF in local coordinates.

You must reimplement this function in a subclass of QGraphicsLayoutItem for layout managers to determine the geometry of your item.

See also setGeometry().

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

This virtual function provides the left, top, right and bottom contents margins for this QGraphicsLayoutItem. The default implementation assumes all contents margins are 0. The values are stored in the qreals pointed to by the input arguments. If any of the pointers is 0, that value will not be updated.

See also QGraphicsWidget::setContentsMargins().

bool QGraphicsLayoutItem::isLayout () const

Returns true if this QGraphicsLayoutItem is a layout (i.e., is inherited by an object that arranges other QGraphicsLayoutItem objects); otherwise returns false.

See also QGraphicsLayout.

QSizeF QGraphicsLayoutItem::maximumSize () const

Returns the maximum size.

See also setMaximumSize(), minimumSize(), preferredSize(), Qt::MaximumSize, and sizeHint().

QSizeF QGraphicsLayoutItem::minimumSize () const

Returns the minimum size.

See also setMinimumSize(), preferredSize(), maximumSize(), Qt::MinimumSize, and sizeHint().

QGraphicsLayoutItem * QGraphicsLayoutItem::parentLayoutItem () const

Returns the parent of this QGraphicsLayoutItem, or 0 if either there is no parent, or if the parent does not inherit from QGraphicsLayoutItem (QGraphicsLayoutItem is often used by multiple inheritance with QObject-derived classes).

See also setParentLayoutItem().

QSizeF QGraphicsLayoutItem::preferredSize () const

Returns the preferred size.

See also setPreferredSize(), minimumSize(), maximumSize(), Qt::PreferredSize, and sizeHint().

void QGraphicsLayoutItem::setGeometry ( const QRectF & rect )   [pure virtual]

This pure virtual function sets the geometry of the QGraphicsLayoutItem to rect, which is in parent coordinates (i.e., the top-left corner of rect is equivalent to the item's position in parent coordinates).

You must reimplement this function in a subclass of QGraphicsLayoutItem for your item to receive geometry updates.

See also geometry().

void QGraphicsLayoutItem::setMaximumSize ( const QSizeF & size )

Sets the maximum size to size. This property overrides sizeHint() for Qt::MaximumSize and ensures that effectiveSizeHint() will never return a size larger than size.

See also maximumSize(), minimumSize(), preferredSize(), Qt::MaximumSize, and sizeHint().

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

This is an overloaded member function, provided for convenience.

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

See also maximumSize(), setMinimumSize(), setPreferredSize(), and sizeHint().

void QGraphicsLayoutItem::setMinimumSize ( const QSizeF & size )

Sets the minimum size to size. This property overrides sizeHint() for Qt::MinimumSize and ensures that effectiveSizeHint() will never return a size smaller than size.

See also minimumSize(), maximumSize(), preferredSize(), Qt::MinimumSize, and sizeHint().

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

This is an overloaded member function, provided for convenience.

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

See also minimumSize(), setMaximumSize(), setPreferredSize(), and sizeHint().

void QGraphicsLayoutItem::setParentLayoutItem ( QGraphicsLayoutItem * parent )

Sets the parent of this QGraphicsLayoutItem to parent.

See also parentLayoutItem().

void QGraphicsLayoutItem::setPreferredSize ( const QSizeF & size )

Sets the preferred size to size. This property overrides sizeHint() for Qt::PreferredSize and provides the default value for effectiveSizeHint().

See also preferredSize(), minimumSize(), maximumSize(), Qt::PreferredSize, and sizeHint().

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

This is an overloaded member function, provided for convenience.

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

See also preferredSize(), setMaximumSize(), setMinimumSize(), and sizeHint().

void QGraphicsLayoutItem::setSizePolicy ( const QSizePolicy & policy )

Sets the size policy to policy. 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's common for subclasses to change the default. For example, QGraphicsWidget defaults to (QSizePolicy::Preferred, QSizePolicy::Preferred, QSizePolicy::DefaultType).

See also sizePolicy() and QWidget::sizePolicy().

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

This is an overloaded member function, provided for convenience.

Equivalent to calling setSizePolicy(QSizePolicy(hPolicy, vPolicy, controlType)).

See also sizePolicy() and QWidget::sizePolicy().

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

This pure virtual function returns the size hint for which of the QGraphicsLayoutItem, using the width or height of constraint to constrain the output.

You must reimplement this function in a subclass of QGraphicsLayoutItem to provide the necessary size hints for your items.

See also effectiveSizeHint().

QSizePolicy QGraphicsLayoutItem::sizePolicy () const

Returns the current size policy.

See also setSizePolicy() and QWidget::sizePolicy().

void QGraphicsLayoutItem::updateGeometry ()   [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.

See also effectiveSizeHint().


Copyright © 2007 Trolltech Trademarks
Qt 4.4.0-tp1