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

Inheritance diagram for QGraphicsLayout:

Public Methods
	QGraphicsLayout (QGraphicsLayoutItem *parent=nullptr)

	~QGraphicsLayout ()

void	activate ()

virtual int	count () const = 0

void	getContentsMargins (qreal left, qreal top, qreal right, qreal bottom) const override

virtual void	invalidate ()

bool	isActivated () const

virtual QGraphicsLayoutItem *	itemAt (int i) const = 0

virtual void	removeAt (int index) = 0

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

void	updateGeometry () override

virtual void	widgetEvent (QEvent *event)

Public Methods inherited from QGraphicsLayoutItem
	QGraphicsLayoutItem (QGraphicsLayoutItem *parent=nullptr, bool isLayout=false)

virtual	~QGraphicsLayoutItem ()

QRectF	contentsRect () const

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

QRectF	geometry () const

QGraphicsItem *	graphicsItem () const

bool	isLayout () const

qreal	maximumHeight () const

QSizeF	maximumSize () const

qreal	maximumWidth () const

qreal	minimumHeight () const

QSizeF	minimumSize () const

qreal	minimumWidth () const

bool	ownedByLayout () const

QGraphicsLayoutItem *	parentLayoutItem () const

qreal	preferredHeight () const

QSizeF	preferredSize () const

qreal	preferredWidth () const

virtual void	setGeometry (const QRectF &rect)

void	setMaximumHeight (qreal height)

void	setMaximumSize (const QSizeF &size)

void	setMaximumSize (qreal w, qreal h)

void	setMaximumWidth (qreal width)

void	setMinimumHeight (qreal height)

void	setMinimumSize (const QSizeF &size)

void	setMinimumSize (qreal w, qreal h)

void	setMinimumWidth (qreal width)

void	setParentLayoutItem (QGraphicsLayoutItem *parent)

void	setPreferredHeight (qreal height)

void	setPreferredSize (const QSizeF &size)

void	setPreferredSize (qreal w, qreal h)

void	setPreferredWidth (qreal width)

void	setSizePolicy (const QSizePolicy &policy)

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

QSizePolicy	sizePolicy () const

Static Public Methods
static bool	instantInvalidatePropagation ()

static void	setInstantInvalidatePropagation (bool enable)

Protected Methods
void	addChildLayoutItem (QGraphicsLayoutItem *layoutItem)

Protected Methods inherited from QGraphicsLayoutItem
void	setGraphicsItem (QGraphicsItem *item)

void	setOwnedByLayout (bool owner)

virtual QSizeF	sizeHint (Qt::SizeHint which, const QSizeF &constraint=QSizeF ()) const = 0

Friends
class	QGraphicsWidget

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 objects for a QGraphicsWidget. QGraphicsWidget assigns responsibility to a QGraphicsLayout through QGraphicsWidget::setLayout(). As the widget is resized, the layout will automatically arrange the widget's children. QGraphicsLayout inherits QGraphicsLayoutItem, so, it can be managed by any layout, including its own subclasses.

Writing a Custom Layout

You can use QGraphicsLayout as a base class to write your own custom layout. It is often more common to use one of the existing subclasses instead like QGraphicsLinearLayout or QGraphicsGridLayout. When creating a custom layout, the following methods must be overridden.

Function	Description
QGraphicsLayoutItem::setGeometry()	Called when the geometry of the layout is set.
QGraphicsLayoutItem::sizeHint()	Returns the layout's size hints.
QGraphicsLayout::count()	Returns the number of items in your layout.
QGraphicsLayout::itemAt()	Returns a pointer to an item in your layout.
QGraphicsLayout::removeAt()	Removes an item from your layout without destroying it.

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.

The method addChildLayoutItem() is used to adjust the ownership when adding layout items to a custom layout.

Activating the Layout

When the layout's geometry changes, QGraphicsLayout immediately rearranges all of its managed items by calling setGeometry() on each item. This rearrangement is called activating the layout.

QGraphicsLayout updates its own geometry to match the contentsRect() of the QGraphicsLayoutItem it is managing. Thus, 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.

A QGraphicsLayout will have the same geometry as the contentsRect() of the widget (not the layout) it is assigned to.

Activating the Layout Implicitly

The layout can be activated implicitly using one of two ways: by calling activate() or by calling invalidate(). Calling activate() activates the layout immediately. In contrast, calling invalidate() is delayed, as it posts a LayoutRequest event to the managed widget. Due to event compression, the activate() will only be called once after control has returned to the event loop. This is referred to as invalidating the layout. Invalidating the layout also invalidates any cached information.

Event Handling

QGraphicsLayout listens to events for the widget it manages through the virtual widgetEvent() event handler. When the layout is assigned to a widget, all events delivered to the widget are first processed by widgetEvent(). This allows the layout to be aware of any relevant state changes on the widget such as visibility changes or layout direction changes.

Margin Handling

The margins of a QGraphicsLayout can be modified by reimplementing setContentsMargins() and getContentsMargins().

See also: invalidate()

Constructor & Destructor Documentation

QGraphicsLayout::QGraphicsLayout ( QGraphicsLayoutItem * parent = nullptr )

Constructs a QGraphicsLayout object. The parent object is passed to the QGraphicsLayoutItem constructor and the QGraphicsLayoutItem's isLayout argument is set to true. If parent is a QGraphicsWidget the layout will be installed on the parent. Installing a new layout will delete the old one if one exists

QGraphicsLayout::~QGraphicsLayout ( )

Destroys the QGraphicsLayout object.

Method Documentation

void QGraphicsLayout::activate ( )

Activates the layout, causing all items in the layout to be immediately rearranged. This function is based on calling count() and itemAt(), and then calling setGeometry() on all items sequentially. 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.

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

void QGraphicsLayout::addChildLayoutItem ( QGraphicsLayoutItem * layoutItem )

protected

This method is provided for custom layouts and will walk through all items in the layout and reparent them to the closest QGraphicsWidget ancestor of the layout. If layoutItem is already in a different layout, the item will be removed from the old layout.

See also: graphicsItem()

int QGraphicsLayout::count ( ) const

pure virtual

This method must be overriden in a subclass of QGraphicsLayout to return the number of items in the layout. The subclass must decide how to store the items.

See also: itemAt(), removeAt()

Implemented in QGraphicsAnchorLayout::count(), QGraphicsGridLayout::count(), QGraphicsLinearLayout::count()

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

overridevirtual

Reimplemented from QGraphicsLayoutItem::getContentsMargins()

bool QGraphicsLayout::instantInvalidatePropagation ( )

static

Returns true if the complete widget/layout hierarchy is rearranged in one go.

See also: setInstantInvalidatePropagation()

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(), setGeometry()

Reimplemented in QGraphicsAnchorLayout::invalidate(), QGraphicsGridLayout::invalidate(), QGraphicsLinearLayout::invalidate()

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(), invalidate()

QGraphicsLayoutItem * QGraphicsLayout::itemAt ( int i ) const

pure virtual

This method must be reimplemented in any class which inherits from QGraphicsLayout and return a pointer to the item at index i.

The reimplementation can assume that i is valid. This method is used with count() to iterate over all items in the layout. The subclass is free to decide how to store the items and the visual arrangement does not have to be reflected through this method.

See also: count(), removeAt()

Implemented in QGraphicsAnchorLayout::itemAt(), QGraphicsGridLayout::itemAt(), QGraphicsLinearLayout::itemAt()

void QGraphicsLayout::removeAt ( int index )

pure virtual

This method must be reimplemented in any class which inherits from QGraphicsLayout to remove the item at index.

The reimplementation can assume index is valid. The implementation must ensure that the parentLayoutItem() of the removed item does not point to this layout, since the item is considered to be removed from the layout hierarchy. If the layout is to be reused between applications, we recommend that the layout deletes the item, but the graphics view system does not depend on this. The subclass is free to decide how to store the items.

See also: itemAt(), count()

Implemented in QGraphicsAnchorLayout::removeAt(), QGraphicsGridLayout::removeAt(), QGraphicsLinearLayout::removeAt()

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 querying 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::setInstantInvalidatePropagation ( bool enable )

static

Calling this method with enable set to true will enable a feature that makes propagation of invalidation up to ancestor layout items to be done in one go. It will propagate up the parentLayoutItem() hierarchy until it has reached the root. If the root item is a QGraphicsWidget, it will post a layout request to it. When the layout request is consumed it will traverse down the hierarchy of layouts and widgets and activate all layouts that is invalid (not activated). This is the recommended behavior.

If not set it will also propagate up the parentLayoutItem() hierarchy, but it will stop at the first widget it encounters, and post a layout request to the widget. When the layout request is consumed, this might cause it to continue propagation up to the parentLayoutItem() of the widget. It will continue in this fashion until it has reached a widget with no parentLayoutItem(). This strategy might cause drawing artifacts, since it is not done in one go, and the consumption of layout requests might be interleaved by consumption of paint events, which might cause significant flicker. Note, this is not the recommended behavior, but for compatibility reasons this is the default behavior.

See also: instantInvalidatePropagation()

void QGraphicsLayout::updateGeometry ( )

overridevirtual

Reimplemented from QGraphicsLayoutItem::updateGeometry()

void QGraphicsLayout::widgetEvent ( QEvent * event )

virtual

This 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 or layout direction changes. The event 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(), QGraphicsItem::sceneEvent()

Public Methods

Static Public Methods

Protected Methods

Friends

Detailed Description

Writing a Custom Layout

Activating the Layout

Activating the Layout Implicitly

Event Handling

Margin Handling

Constructor & Destructor Documentation

Method Documentation