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

QGraphicsLayout Class Reference
[
QtGui module]

The QGraphicsLayout class provides the base class for all layouts in Graphics View. More...

 #include <QGraphicsLayout>

Inherits QGraphicsLayoutItem.

Inherited by QGraphicsGridLayout and QGraphicsLinearLayout.

This class was introduced in Qt 4.4.

Public Functions

Additional Inherited Members


Detailed Description

The QGraphicsLayout class provides the base class for all layouts in Graphics View.

QGraphicsLayout is an abstract class that defines a virtual API for arranging QGraphicsWidget children and other QGraphicsLayoutItem items for a QGraphicsWidget. QGraphicsWidget assigns responsibility to a QGraphicsWidget through QGraphicsWidget::setLayout(). As the widget is resized, the layout will automatically arrange the widget's children.

You can use this class as a base when writing your own custom layout (e.g., a flowlayout), but it's more common to use one of its subclasses, QGraphicsLinearLayout and QGraphicsGridLayout, directly instead.

When the geometry changes, QGraphicsLayout immediately rearranges the QGraphicsLayoutItem items it is managing by calling setGeometry() on each item. This rearrangement is what we refer to as "activating" the layout. QGraphicsLayout always updates its own geometry to match the contentsRect() of the QGraphicsLayoutItem it is managing (i.e., a QGraphicsLayout will always have the same geometry as the contents rect of the QGraphicsWidget it is assigned to), and because of this, it will automatically rearrange all its items when the widget is resized. QGraphicsLayout caches the sizes of all its managed items to avoid calling setGeometry() too often.

There are also two implicit ways to trigger an activation. By calling activate(), you activate the layout immediately. In contrast, calling invalidate() is delayed, it will post a LayoutRequest event to the managed widget, and through event compression this ensures that activate() will be called only once after control has returned to the event loop. This is referred to as "invalidating" the layout. Activation is always immediate, invalidating is always delayed. Invalidating the layout also invalidates any cached information - invalidate() is a virtual function, so you can invalidate your own cache in a subclass of QGraphicsLayout by reimplementing this function.

QGraphicsLayout listens to events for its managed widget through the virtual widgetEvent() event handler. When assigned to a widget, all events that are delivered to the widget are first processed by widgetEvent(). This allows the layout to become aware of any relevant state changes to the widget (e.g., visibility changes or layout direction changes).

When creating a subclass of QGraphicsLayout, you must implement three pure virtual functions for managing QGraphicsLayoutItem items. The count() function should return the number of items that are currently managed. itemAt() should return a pointer any of the managed items, and removeAt() removes an item at an index. These virtual functions are called by QGraphicsLayout and used when rearranging the managed items. The subclass decides how these items are stored.

QGraphicsLayout provides content margin management through reimplementations of setContentsMargins() and getContentsMargins().

Because it inherits QGraphicsLayoutItem, QGraphicsLayout can itself also be managed by any layout, including its own subclasses.


Member Function Documentation

QGraphicsLayout::QGraphicsLayout ( QGraphicsLayoutItem * parent = 0 )

Contructs a QGraphicsLayout object. parent is passed to QGraphicsLayoutItem's constructor (and QGraphicsLayoutItem's isLayout argument is set to true).

QGraphicsLayout::~QGraphicsLayout ()

Destroys the QGraphicsLayout object.

void QGraphicsLayout::activate ()

Activates the layout, causing an immediate rearrangement of all items in the layout. This function is based on calling count() and itemAt(), and then calling setGeometry() in sequence on all items. When activated, the layout will adjust its geometry to its parent's contentsRect(). The parent will then invalidate any layout of its own.

If called in sequence or recursively, (e.g., by one of the arranged items in response to being resized,) this function will do nothing.

Note that the layout is free to use geometry caching to optimize this process. To forcefully invalidate any such cache, you can call invalidate() before calling activate().

See also invalidate().

int QGraphicsLayout::count () const   [pure virtual]

This pure virtual function must be reimplemented in a subclass of QGraphicsLayout to return the number of items in the layout.

The subclass is free to decide how to store the items.

See also itemAt() and removeAt().

void QGraphicsLayout::invalidate ()   [virtual]

Clears any cached geometry and size hint information in the layout, and posts a LayoutRequest event to the managed parent QGraphicsLayoutItem.

See also activate() and setGeometry().

bool QGraphicsLayout::isActivated () const

Returns true if the layout is currently being activated; otherwise, returns false. If the layout is being activated, this means that it is currently in the process of rearranging its items (i.e., the activate() function has been called, and has not yet returned).

See also activate() and invalidate().

QGraphicsLayoutItem * QGraphicsLayout::itemAt ( int i ) const   [pure virtual]

This pure virtual function must be reimplemented in a subclass of QGraphicsLayout to return a pointer to the item at index i. The reimplementation can assume that i is valid (i.e., it respects the value of count()).

The subclass is free to decide how to store the items.

See also count() and removeAt().

void QGraphicsLayout::removeAt ( int i )   [pure virtual]

This pure virtual function must be reimplemented in a subclass of QGraphicsLayout to remove the item at index i. The reimplementation can assume that i is valid (i.e., it respects the value of count()).

The subclass is free to decide how to store the items.

See also itemAt() and count().

void QGraphicsLayout::setContentsMargins ( qreal left, qreal top, qreal right, qreal bottom )

Sets the contents margins to left, top, right and bottom. The default contents margins for toplevel layouts are style dependent (by quering the pixelMetric for QStyle::PM_LayoutLeftMargin, QStyle::PM_LayoutTopMargin, QStyle::PM_LayoutRightMargin and QStyle::PM_LayoutBottomMargin For sublayouts the default margins are 0.

Changing the contents margins automatically invalidates the layout.

See also invalidate().

void QGraphicsLayout::widgetEvent ( QEvent * e )   [virtual]

This virtual event handler receives all events for the managed widget. QGraphicsLayout uses this event handler to listen for layout related events such as geometry changes, layout changes and layout direction changes. e is a pointer to the event.

You can reimplement this event handler to track similar events for your own custom layout.

See also QGraphicsWidget::event() and QGraphicsItem::sceneEvent().


Copyright © 2007 Trolltech Trademarks
Qt 4.4.0-tp1