CopperSpice API  1.7.2
QLayout Class Referenceabstract

The QLayout class is the base class of geometry managers. More...

Inheritance diagram for QLayout:
QObject QLayoutItem QBoxLayout QFormLayout QGridLayout QStackedLayout QHBoxLayout QVBoxLayout

Public Types

enum  SizeConstraint
 

Public Methods

 QLayout ()
 
 QLayout (QWidget *parent)
 
bool activate ()
 
virtual void addItem (QLayoutItem *item) = 0
 
void addWidget (QWidget *w)
 
QMargins contentsMargins () const
 
QRect contentsRect () const
 
QSizePolicy::ControlTypes controlTypes () const override
 
virtual int count () const = 0
 
Qt::Orientations expandingDirections () const override
 
QRect geometry () const override
 
void getContentsMargins (int *left, int *top, int *right, int *bottom) const
 
virtual int indexOf (QWidget *widget) const
 
void invalidate () override
 
bool isEmpty () const override
 
bool isEnabled () const
 
virtual QLayoutItemitemAt (int index) const = 0
 
QLayout * layout () override
 
int margin () const
 
QSize maximumSize () const override
 
QWidgetmenuBar () const
 
QSize minimumSize () const override
 
QWidgetparentWidget () const
 
void removeItem (QLayoutItem *item)
 
void removeWidget (QWidget *widget)
 
virtual QLayoutItemreplaceWidget (QWidget *from, QWidget *to, Qt::FindChildOptions options=Qt::FindChildrenRecursively)
 
bool setAlignment (QLayout *layout, Qt::Alignment alignment)
 
void setAlignment (Qt::Alignment alignment)
 
bool setAlignment (QWidget *widget, Qt::Alignment alignment)
 
void setContentsMargins (const QMargins &margins)
 
void setContentsMargins (int left, int top, int right, int bottom)
 
void setEnabled (bool enable)
 
void setGeometry (const QRect &rect) override
 
void setMargin (int margin)
 
void setMenuBar (QWidget *widget)
 
void setSizeConstraint (SizeConstraint constraint)
 
void setSpacing (int spacing)
 
SizeConstraint sizeConstraint () const
 
int spacing () const
 
virtual QLayoutItemtakeAt (int index) = 0
 
void update ()
 
- Public Methods inherited from QObject
 QObject (QObject *parent=nullptr)
 
 ~QObject ()
 
bool blockSignals (bool block)
 
const QList< QObject * > & children () const
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QStringdynamicPropertyNames () const
 
virtual bool event (QEvent *event)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
template<typename T >
findChild (const QString &childName=QString ()) const
 
template<class T >
QList< T > findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
template<class T >
QList< T > findChildren (const QString &objName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
bool inherits (const QString &className) const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const
 
bool isWindowType () const
 
void killTimer (int id)
 
const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
property (const QString &name) const
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const QString &name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 
QThreadthread () const
 
- Public Methods inherited from QLayoutItem
 QLayoutItem (Qt::Alignment alignment=Qt::Alignment ())
 
virtual ~QLayoutItem ()
 
Qt::Alignment alignment () const
 
virtual bool hasHeightForWidth () const
 
virtual int heightForWidth (int width) const
 
virtual int minimumHeightForWidth (int width) const
 
void setAlignment (Qt::Alignment alignment)
 
virtual QSize sizeHint () const = 0
 
virtual QSpacerItemspacerItem ()
 
virtual QWidgetwidget ()
 

Static Public Methods

static QSize closestAcceptableSize (const QWidget *widget, const QSize &size)
 
- Static Public Methods inherited from QObject
static bool connect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool connect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())
 
static bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...))
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)
 
static QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 

Protected Methods

void addChildLayout (QLayout *layout)
 
void addChildWidget (QWidget *widget)
 
QRect alignmentRect (const QRect &rect) const
 
void childEvent (QChildEvent *event) override
 
- Protected Methods inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signalMethod) const
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signalMethod) const
 
bool isSignalConnected (const QMetaMethod &signalMethod) const
 
int receivers (const QString &signal) const
 
QObject * sender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 

Properties

 margin
 
 sizeConstraint
 
 spacing
 
- Properties inherited from QObject
 objectName
 

Friends

class QWidget
 

Additional Inherited Members

- Public Signals inherited from QObject
void destroyed (QObject *obj=nullptr)
 
void objectNameChanged (const QString &objectName)
 
- Public Slots inherited from QObject
void deleteLater ()
 

Detailed Description

The QLayout class is the base class of geometry managers.

This is an abstract base class inherited by the concrete classes QBoxLayout, QGridLayout, QFormLayout, and QStackedLayout.

For users of QLayout subclasses or of QMainWindow there is seldom any need to use the basic functions provided by QLayout, such as setSizeConstraint() or setMenuBar().

To make your own layout manager, implement the functions addItem(), sizeHint(), setGeometry(), itemAt() and takeAt(). You should also implement minimumSize() to ensure your layout is not resized to zero size if there is too little space. To support children whose heights depend on their widths, implement hasHeightForWidth() and heightForWidth().

Geometry management stops when the layout manager is deleted.

See also
QLayoutItem, Layout Management

Member Enumeration Documentation

The possible values are:

ConstantValueDescription
QLayout::SetDefaultConstraint0The main widget's minimum size is set to minimumSize(), unless the widget already has a minimum size.
QLayout::SetFixedSize3The main widget's size is set to sizeHint(); it can not be resized at all.
QLayout::SetMinimumSize2The main widget's minimum size is set to minimumSize(); it can not be smaller.
QLayout::SetMaximumSize4The main widget's maximum size is set to maximumSize(); it can not be larger.
QLayout::SetMinAndMaxSize5The main widget's minimum size is set to minimumSize() and its maximum size is set to maximumSize().
QLayout::SetNoConstraint1The widget is not constrained.
See also
setSizeConstraint()

Constructor & Destructor Documentation

QLayout::QLayout ( QWidget parent)

Constructs a new top-level QLayout, with parent parent. parent may not be 0.

There can be only one top-level layout for a widget. It is returned by QWidget::layout().

QLayout::QLayout ( )

Constructs a new child QLayout.

This layout has to be inserted into another layout before geometry management will work.

Method Documentation

bool QLayout::activate ( )

Redoes the layout for parentWidget() if necessary.

You should generally not need to call this because it is automatically called at the most appropriate times. It returns true if the layout was redone.

See also
update(), QWidget::updateGeometry()
void QLayout::addChildLayout ( QLayout *  layout)
protected

This function is called from addLayout() or insertLayout() functions in subclasses to add layout as a sub-layout.

The only scenario in which you need to call it directly is if you implement a custom layout that supports nested layouts.

See also
QBoxLayout::addLayout(), QBoxLayout::insertLayout(), QGridLayout::addLayout()
void QLayout::addChildWidget ( QWidget widget)
protected

This function is called from addWidget() functions in subclasses to add widget as a managed widget of a layout.

If widget is already managed by a layout, this function will give a warning and remove widget from that layout. This function must therefore be called before adding widget to the layout's data structure.

void QLayout::addItem ( QLayoutItem item)
pure virtual

Implemented in subclasses to add an item. How it is added is specific to each subclass.

This function is not usually called in application code. To add a widget to a layout, use the addWidget() function; to add a child layout, use the addLayout() function provided by the relevant QLayout subclass.

Note
The ownership of item is transferred to the layout, and it's the layout's responsibility to delete it.
See also
addWidget(), QBoxLayout::addLayout(), QGridLayout::addLayout()

Implemented in QFormLayout, QGridLayout, QStackedLayout, and QBoxLayout.

void QLayout::addWidget ( QWidget w)

Adds widget w to this layout in a manner specific to the layout. This function uses addItem().

QRect QLayout::alignmentRect ( const QRect rect) const
protected

Returns the rectangle that should be covered when the geometry of this layout is set to rect, provided that this layout supports setAlignment(). The result is derived from sizeHint() and expanding(). It is never larger than rect.

void QLayout::childEvent ( QChildEvent event)
overrideprotected

Reimplemented from QObject::childEvent().

QSize QLayout::closestAcceptableSize ( const QWidget widget,
const QSize size 
)
static

Returns a size that satisfies all size constraints on widget, including heightForWidth() and that is as close as possible to size.

QMargins QLayout::contentsMargins ( ) const

Returns the margins used around the layout.

By default, QLayout uses the values provided by the style. On most platforms, the margin is 11 pixels in all directions.

See also
setContentsMargins()
QRect QLayout::contentsRect ( ) const

Returns the layout's geometry() rectangle, but taking into account the contents margins.

See also
setContentsMargins(), getContentsMargins()
QSizePolicy::ControlTypes QLayout::controlTypes ( ) const
overridevirtual

Returns the control type(s) for the layout item. For a QWidgetItem, the control type comes from the widget's size policy; for a QLayoutItem, the control types is derived from the layout's contents.

See also
QSizePolicy::controlType()

Reimplemented from QLayoutItem.

int QLayout::count ( ) const
pure virtual

Must be implemented in subclasses to return the number of items in the layout.

See also
itemAt()

Implemented in QFormLayout, QGridLayout, QBoxLayout, and QStackedLayout.

Qt::Orientations QLayout::expandingDirections ( ) const
overridevirtual

Reimplemented from QLayoutItem::expandingDirections().

Returns whether this layout can make use of more space than sizeHint(). A value of Qt::Vertical or Qt::Horizontal means that it wants to grow in only one dimension, whereas Qt::Vertical | Qt::Horizontal means that it wants to grow in both dimensions.

The default implementation returns Qt::Horizontal | Qt::Vertical. Subclasses reimplement it to return a meaningful value based on their child widget's size policies.

See also
sizeHint()

Implements QLayoutItem.

QRect QLayout::geometry ( ) const
overridevirtual

Reimplemented from QLayoutItem::geometry().

See also
setGeometry()

Implements QLayoutItem.

void QLayout::getContentsMargins ( int *  left,
int *  top,
int *  right,
int *  bottom 
) const

Extracts the left, top, right, and bottom margins used around the layout, and assigns them to left, top, right, and bottom (unless they are null pointers).

By default, QLayout uses the values provided by the style. On most platforms, the margin is 11 pixels in all directions.

See also
setContentsMargins(), QStyle::pixelMetric(), PM_LayoutLeftMargin, PM_LayoutTopMargin, PM_LayoutRightMargin, PM_LayoutBottomMargin
int QLayout::indexOf ( QWidget widget) const
virtual

Searches for widget widget in this layout (not including child layouts). Returns the index of widget, or -1 if widget is not found. The default implementation iterates over all items using itemAt().

void QLayout::invalidate ( )
overridevirtual

Reimplemented from QLayoutItem::invalidate().

Reimplemented from QLayoutItem.

bool QLayout::isEmpty ( ) const
overridevirtual

Reimplemented from QLayoutItem::isEmpty().

Implements QLayoutItem.

bool QLayout::isEnabled ( ) const

Returns true if the layout is enabled, otherwise returns false.

See also
setEnabled()
QLayoutItem * QLayout::itemAt ( int  index) const
pure virtual

Must be implemented in subclasses to return the layout item at index. If there is no such item, the method must return a nullptr. Items are numbered consecutively starting from 0. If an item is deleted, other items will be renumbered.

This method can be used to iterate over a layout. The following code will draw a rectangle for each layout item in the layout structure of the widget.

static void paintLayout(QPainter *painter, QLayoutItem *item) {
QLayout *layout = item->layout();
if (layout) {
for (int i = 0; i < layout->count(); ++i) {
paintLayout(painter, layout->itemAt(i));
}
}
painter->drawRect(item->geometry());
}
void MyWidget::paintEvent(QPaintEvent *) {
QPainter painter(this);
if (layout()) {
paintLayout(&painter, layout());
}
}
See also
count(), takeAt()

Implemented in QFormLayout, QGridLayout, QBoxLayout, and QStackedLayout.

QLayout * QLayout::layout ( )
overridevirtual

Reimplemented from QLayoutItem::layout().

Reimplemented from QLayoutItem.

int QLayout::margin ( ) const

Returns the value of the property.

QSize QLayout::maximumSize ( ) const
overridevirtual

Returns the maximum size of this layout. This is the largest size that the layout can have while still respecting the specifications. The returned value does not include the space required by QWidget::setContentsMargins() or menuBar(). The default implementation allows unlimited resizing.

Implements QLayoutItem.

QWidget * QLayout::menuBar ( ) const

Returns the menu bar set for this layout or a nullptr if no menu bar is set.

See also
setMenuBar()
QSize QLayout::minimumSize ( ) const
overridevirtual

Returns the minimum size of this layout. This is the smallest size that the layout can have while still respecting the specifications. The returned value does not include the space required by QWidget::setContentsMargins() or menuBar(). The default implementation allows unlimited resizing.

Implements QLayoutItem.

Reimplemented in QStackedLayout.

QWidget * QLayout::parentWidget ( ) const

Returns the parent widget of this layout or a nullptr if this layout is not installed on any widget. If the layout is a sub-layout, this function returns the parent widget of the parent layout.

See also
parent()
void QLayout::removeItem ( QLayoutItem item)

Removes the layout item item from the layout. It is the caller's responsibility to delete the item. Notice that item can be a layout (since QLayout inherits QLayoutItem).

See also
removeWidget(), addItem()
void QLayout::removeWidget ( QWidget widget)

Removes the widget widget from the layout. After this call, it is the caller's responsibility to give the widget a reasonable geometry or to put the widget back into a layout.

Note
The ownership of widget remains the same as when it was added.
See also
removeItem(), QWidget::setGeometry(), addWidget()
QLayoutItem * QLayout::replaceWidget ( QWidget from,
QWidget to,
Qt::FindChildOptions  options = Qt::FindChildrenRecursively 
)
virtual

Searches for widget from and replaces it with widget to if found. Returns the layout item that contains the widget from on success. Otherwise 0 is returned. If options contains Qt::FindChildrenRecursively (the default), sub-layouts are searched for doing the replacement. Any other flag in options is ignored.

Notice that the returned item therefore might not belong to this layout, but to a sub-layout.

The returned layout item is no longer owned by the layout and should be either deleted or inserted to another layout. The widget from is no longer managed by the layout and may need to be deleted or hidden. The parent of widget from is left unchanged.

This method works for the built in layouts but might not work for custom layouts.

See also
indexOf()
bool QLayout::setAlignment ( QLayout *  layout,
Qt::Alignment  alignment 
)

Sets the alignment for the layout to alignment and returns true if layout is found in this QLayout (not including child layouts), otherwise returns false.

void QLayoutItem::setAlignment ( Qt::Alignment  alignment)
using

Sets the alignment of this item to alignment.

Item alignment is only supported by some child classes.

See also
alignment()
bool QLayout::setAlignment ( QWidget widget,
Qt::Alignment  alignment 
)

Sets the alignment for widget to alignment and returns true if widget is found in this layout (not including child layouts), otherwise returns false.

void QLayout::setContentsMargins ( const QMargins margins)

Sets the margins to use around the layout. By default, QLayout uses the values provided by the style. On most platforms the margin is 11 pixels in all directions.

See also
contentsMargins()
void QLayout::setContentsMargins ( int  left,
int  top,
int  right,
int  bottom 
)

Sets the left, top, right, and bottom margins to use around the layout. By default, QLayout uses the values provided by the style. On most platforms, the margin is 11 pixels in all directions.

See also
contentsMargins(), getContentsMargins(), QStyle::pixelMetric(), PM_LayoutLeftMargin, PM_LayoutTopMargin, PM_LayoutRightMargin, PM_LayoutBottomMargin
void QLayout::setEnabled ( bool  enable)

Enables this layout if enable is true, otherwise disables it. An enabled layout adjusts dynamically to changes a disabled layout acts as if it did not exist. By default all layouts are enabled.

See also
isEnabled()
void QLayout::setGeometry ( const QRect rect)
overridevirtual

Reimplemented from QLayoutItem::setGeometry().

See also
geometry()

Implements QLayoutItem.

Reimplemented in QStackedLayout.

void QLayout::setMargin ( int  margin)

Sets the value of the property to margin.

void QLayout::setMenuBar ( QWidget widget)

Tells the geometry manager to place the menu bar widget at the top of parentWidget(), outside QWidget::contentsMargins(). All child widgets are placed below the bottom edge of the menu bar.

See also
menuBar()
void QLayout::setSizeConstraint ( SizeConstraint  constraint)

Sets the value of the property to mconstraint.

void QLayout::setSpacing ( int  spacing)

Sets the value of the property to spacing.

SizeConstraint QLayout::sizeConstraint ( ) const

Property documentation pending.

int QLayout::spacing ( ) const

Property documentation pending.

QLayoutItem * QLayout::takeAt ( int  index)
pure virtual

Must be implemented in subclasses to remove the layout item at index from the layout, and return the item. If there is no such item, the method must do nothing and return a nullptr. Items are numbered consecutively from 0. If an item is removed, other items will be renumbered.

The following code fragment shows a safe way to remove all items from a layout:

QLayoutItem *child;
while ((child = layout->takeAt(0)) != 0) {
...
delete child;
}
See also
itemAt(), count()

Implemented in QFormLayout, QGridLayout, QBoxLayout, and QStackedLayout.

void QLayout::update ( )

Updates the layout for parentWidget().

You should generally not need to call this because it is automatically called at the most appropriate times.

See also
activate(), invalidate()

Property Documentation

QLayout::margin
deprecated
Deprecated:
This property holds the width of the outside border of the layout.

Use setContentsMargins() and getContentsMargins() instead.

See also
contentsRect(), spacing
PropertiesClass Methods
read margin
write setMargin
QLayout::sizeConstraint

This property holds the resize mode of the layout.

The default mode is SetDefaultConstraint.

PropertiesClass Methods
read sizeConstraint
write setSizeConstraint
QLayout::spacing

This property holds the spacing between widgets inside the layout.

If no value is explicitly set, the layout's spacing is inherited from the parent layout, or from the style settings for the parent widget.

For QGridLayout and QFormLayout, it is possible to set different horizontal and vertical spacings using setHorizontalSpacing() and setVerticalSpacing(). In that case, spacing() returns -1.

See also
contentsRect(), getContentsMargins(), QStyle::layoutSpacing(), QStyle::pixelMetric()
PropertiesClass Methods
read spacing
write setSpacing