CopperSpice API  1.7.2
QGridLayout Class Reference

The QGridLayout class lays out widgets in a grid. More...

Inheritance diagram for QGridLayout:
QLayout QObject QLayoutItem

Public Methods

 QGridLayout ()
 
 QGridLayout (QWidget *parent)
 
 ~QGridLayout ()
 
void addItem (QLayoutItem *item, int row, int column, int rowSpan=1, int columnSpan=1, Qt::Alignment alignment=Qt::Alignment ())
 
void addLayout (QLayout *layout, int row, int column, int rowSpan, int columnSpan, Qt::Alignment alignment=Qt::Alignment ())
 
void addLayout (QLayout *layout, int row, int column, Qt::Alignment alignment=Qt::Alignment ())
 
void addWidget (QWidget *widget, int row, int column, int rowSpan, int columnSpan, Qt::Alignment alignment=Qt::Alignment ())
 
void addWidget (QWidget *widget, int row, int column, Qt::Alignment alignment=Qt::Alignment ())
 
QRect cellRect (int row, int column) const
 
int columnCount () const
 
int columnMinimumWidth (int column) const
 
int columnStretch (int column) const
 
int count () const override
 
Qt::Orientations expandingDirections () const override
 
void getItemPosition (int index, int *row, int *column, int *rowSpan, int *columnSpan) const
 
bool hasHeightForWidth () const override
 
int heightForWidth (int width) const override
 
int horizontalSpacing () const
 
void invalidate () override
 
QLayoutItemitemAt (int index) const override
 
QLayoutItemitemAtPosition (int row, int column) const
 
QSize maximumSize () const override
 
int minimumHeightForWidth (int width) const override
 
QSize minimumSize () const override
 
Qt::Corner originCorner () const
 
int rowCount () const
 
int rowMinimumHeight (int row) const
 
int rowStretch (int row) const
 
void setColumnMinimumWidth (int column, int minSize)
 
void setColumnStretch (int column, int stretch)
 
void setGeometry (const QRect &rect) override
 
void setHorizontalSpacing (int spacing)
 
void setOriginCorner (Qt::Corner corner)
 
void setRowMinimumHeight (int row, int minSize)
 
void setRowStretch (int row, int stretch)
 
void setSpacing (int spacing)
 
void setVerticalSpacing (int spacing)
 
QSize sizeHint () const override
 
int spacing () const
 
QLayoutItemtakeAt (int index) override
 
int verticalSpacing () const
 
- Public Methods inherited from QLayout
 QLayout ()
 
 QLayout (QWidget *parent)
 
bool activate ()
 
void addWidget (QWidget *w)
 
QMargins contentsMargins () const
 
QRect contentsRect () const
 
QSizePolicy::ControlTypes controlTypes () const override
 
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
 
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
 
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
 
void setAlignment (Qt::Alignment alignment)
 
virtual QSpacerItemspacerItem ()
 
virtual QWidgetwidget ()
 

Protected Methods

void addItem (QLayoutItem *item) override
 
- Protected Methods inherited from QLayout
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

 horizontalSpacing
 
 verticalSpacing
 
- Properties inherited from QLayout
 margin
 
 sizeConstraint
 
 spacing
 
- Properties inherited from QObject
 objectName
 

Additional Inherited Members

- Public Types inherited from QLayout
enum  SizeConstraint
 
- Public Signals inherited from QObject
void destroyed (QObject *obj=nullptr)
 
void objectNameChanged (const QString &objectName)
 
- Public Slots inherited from QObject
void deleteLater ()
 
- Static Public Methods inherited from QLayout
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 >())
 

Detailed Description

The QGridLayout class lays out widgets in a grid.

QGridLayout takes the space made available to it (by its parent layout or by the parentWidget()), divides it up into rows and columns, and puts each widget it manages into the correct cell.

Columns and rows behave identically; we will discuss columns, but there are equivalent functions for rows.

Each column has a minimum width and a stretch factor. The minimum width is the greatest of that set using setColumnMinimumWidth() and the minimum width of each widget in that column. The stretch factor is set using setColumnStretch() and determines how much of the available space the column will get over and above its necessary minimum.

Normally, each managed widget or layout is put into a cell of its own using addWidget(). It is also possible for a widget to occupy multiple cells using the row and column spanning overloads of addItem() and addWidget(). If you do this, QGridLayout will guess how to distribute the size over the columns/rows (based on the stretch factors).

To remove a widget from a layout, call removeWidget(). Calling QWidget::hide() on a widget also effectively removes the widget from the layout until QWidget::show() is called.

This illustration shows a fragment of a dialog with a five-column, three-row grid (the grid is shown overlaid in magenta):

Columns 0, 2 and 4 in this dialog fragment are made up of a QLabel, a QLineEdit, and a QListBox. Columns 1 and 3 are placeholders made with setColumnMinimumWidth(). Row 0 consists of three QLabel objects, row 1 of three QLineEdit objects and row 2 of three QListBox objects. We used placeholder columns (1 and 3) to get the right amount of space between the columns.

Note that the columns and rows are not equally wide or tall. If you want two columns to have the same width, you must set their minimum widths and stretch factors to be the same yourself. You do this using setColumnMinimumWidth() and setColumnStretch().

If the QGridLayout is not the top-level layout (i.e. does not manage all of the widget's area and children), you must add it to its parent layout when you create it, but before you do anything with it. The normal way to add a layout is by calling addLayout() on the parent layout.

Once you have added your layout you can start putting widgets and other layouts into the cells of your grid layout using addWidget(), addItem(), and addLayout().

QGridLayout also includes two margin widths: the contents margin and the spacing(). The contents margin is the width of the reserved space along each of the QGridLayout's four sides. The spacing() is the width of the automatically allocated spacing between neighboring boxes.

The default contents margin values are provided by the style. The default value CopperSpice styles specify is 9 for child widgets and 11 for windows. The spacing defaults to the same as the margin width for a top-level layout, or to the same as the parent layout.

See also
QBoxLayout, QStackedLayout, Layout Management

Constructor & Destructor Documentation

QGridLayout::QGridLayout ( QWidget parent)
explicit

Constructs a new QGridLayout with the given parent. The layout has one row and one column and will expand when new items are inserted.

QGridLayout::QGridLayout ( )

Constructs a new grid layout.

You must insert this grid into another layout. You can insert widgets and layouts into this layout at any time, but laying out will not be performed before this is inserted into another layout.

QGridLayout::~QGridLayout ( )

Destroys the grid layout. Geometry management is terminated if this is a top-level grid. The layout's widgets are not destroyed.

Method Documentation

void QGridLayout::addItem ( QLayoutItem item)
overrideprotectedvirtual

Reimplemented from QLayout::addItem().

Implements QLayout.

void QGridLayout::addItem ( QLayoutItem item,
int  row,
int  column,
int  rowSpan = 1,
int  columnSpan = 1,
Qt::Alignment  alignment = Qt::Alignment() 
)

Adds item at position row, column, spanning rowSpan and columnSpan. The widget is aligned according to the given alignment. If the rowSpan or columnSpan is -1 then the item will extend to the bottom or right edge, respectively. The layout takes ownership of the item.

Warning
Do not use this method to add child layouts or child widget items. Use addLayout() or addWidget() instead.
void QGridLayout::addLayout ( QLayout layout,
int  row,
int  column,
int  rowSpan,
int  columnSpan,
Qt::Alignment  alignment = Qt::Alignment() 
)

This version adds the layout to the cell grid, spanning multiple rows/columns. The cell will start at row, column spanning rowSpan rows and columnSpan columns.

If rowSpan or columnSpan is -1, then the layout will extend to the bottom or right edge, respectively.

void QGridLayout::addLayout ( QLayout layout,
int  row,
int  column,
Qt::Alignment  alignment = Qt::Alignment() 
)

Places the layout at position row, column in the grid. The top-left position is (0, 0). The alignment is specified by alignment. The default alignment is 0, which means that the widget fills the entire cell. A non-zero alignment indicates that the layout should not grow to fill the available space but should be sized according to sizeHint().

The layout becomes a child of the grid layout.

void QGridLayout::addWidget ( QWidget widget,
int  row,
int  column,
int  rowSpan,
int  columnSpan,
Qt::Alignment  alignment = Qt::Alignment() 
)

Adds widget at position row, column, spanning rowSpan and columnSpan. The widget is aligned according to the given alignment. If the rowSpan or columnSpan is -1 then the item will extend to the bottom or right edge, respectively.

void QGridLayout::addWidget ( QWidget widget,
int  row,
int  column,
Qt::Alignment  alignment = Qt::Alignment() 
)

Adds the widget to position row, column. The top-left position is (0, 0) by default. The alignment is specified by alignment. The default alignment will fill the entire cell.

QRect QGridLayout::cellRect ( int  row,
int  column 
) const

Returns the geometry of the cell with row and column in the grid. Returns an invalid rectangle if row or column are outside the grid.

Warning
This method does not return valid results until setGeometry() has been called after the parentWidget() is visible.
int QGridLayout::columnCount ( ) const

Returns the number of columns in this grid.

int QGridLayout::columnMinimumWidth ( int  column) const

Returns the column spacing for column.

See also
setColumnMinimumWidth()
int QGridLayout::columnStretch ( int  column) const

Returns the stretch factor for column.

See also
setColumnStretch()
int QGridLayout::count ( ) const
overridevirtual

Reimplemented from QLayout::count().

Implements QLayout.

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

Reimplemented from QLayoutItem::expandingDirections().

Implements QLayoutItem.

void QGridLayout::getItemPosition ( int  index,
int *  row,
int *  column,
int *  rowSpan,
int *  columnSpan 
) const

Returns the position information of the item with the given index.

The variables passed as row and column are updated with the position of the item in the layout and the rowSpan and columnSpan variables are updated with the vertical and horizontal spans of the item.

See also
itemAtPosition(), itemAt()
bool QGridLayout::hasHeightForWidth ( ) const
overridevirtual

Reimplemented from QLayoutItem::hasHeightForWidth().

Reimplemented from QLayoutItem.

int QGridLayout::heightForWidth ( int  width) const
overridevirtual

Reimplemented from QLayoutItem::heightForWidth().

Reimplemented from QLayoutItem.

int QGridLayout::horizontalSpacing ( ) const

Property documentation pending.

void QGridLayout::invalidate ( )
overridevirtual

Reimplemented from QLayoutItem::invalidate().

Reimplemented from QLayoutItem.

QLayoutItem * QGridLayout::itemAt ( int  index) const
overridevirtual

Reimplemented from QLayout::itemAt().

Implements QLayout.

QLayoutItem * QGridLayout::itemAtPosition ( int  row,
int  column 
) const

Returns the layout item that occupies row, column, or a nullptr if the cell is empty.

See also
getItemPosition(), indexOf()
QSize QGridLayout::maximumSize ( ) const
overridevirtual

Reimplemented from QLayoutItem::maximumSize().

Implements QLayoutItem.

int QGridLayout::minimumHeightForWidth ( int  width) const
overridevirtual

Reimplemented from QLayoutItem::minimumHeightForWidth().

Reimplemented from QLayoutItem.

QSize QGridLayout::minimumSize ( ) const
overridevirtual

Reimplemented from QLayoutItem::minimumSize().

Implements QLayoutItem.

Qt::Corner QGridLayout::originCorner ( ) const

Returns the corner that is used for the origin of the grid.

See also
setOriginCorner()
int QGridLayout::rowCount ( ) const

Returns the number of rows in this grid.

int QGridLayout::rowMinimumHeight ( int  row) const

Returns the minimum width set for row.

See also
setRowMinimumHeight()
int QGridLayout::rowStretch ( int  row) const

Returns the stretch factor for row.

See also
setRowStretch()
void QGridLayout::setColumnMinimumWidth ( int  column,
int  minSize 
)

Sets the minimum width of column to minSize pixels.

See also
columnMinimumWidth(), setRowMinimumHeight()
void QGridLayout::setColumnStretch ( int  column,
int  stretch 
)

Sets the stretch factor of column to stretch. The first column is number 0.

The stretch factor is relative to the other columns in this grid. Columns with a higher stretch factor take more of the available space. The default stretch factor is 0. If the stretch factor is 0 and no other column in this table can grow at all, the column may still grow. An alternative approach is to add spacing using addItem() with a QSpacerItem.

See also
columnStretch(), setRowStretch()
void QGridLayout::setGeometry ( const QRect rect)
overridevirtual

Reimplemented from QLayoutItem::setGeometry().

Implements QLayoutItem.

void QGridLayout::setHorizontalSpacing ( int  spacing)

Property documentation pending.

void QGridLayout::setOriginCorner ( Qt::Corner  corner)

Sets the origin of the grid to the value of corner.

See also
originCorner()
void QGridLayout::setRowMinimumHeight ( int  row,
int  minSize 
)

Sets the minimum height of row to minSize pixels.

See also
rowMinimumHeight(), setColumnMinimumWidth()
void QGridLayout::setRowStretch ( int  row,
int  stretch 
)

Sets the stretch factor of row to stretch. The first row is number 0.

The stretch factor is relative to the other rows in this grid. Rows with a higher stretch factor take more of the available space. The default stretch factor is 0. If the stretch factor is 0 and no other row in this table can grow at all, the row may still grow.

See also
rowStretch(), setRowMinimumHeight(), setColumnStretch()
void QGridLayout::setSpacing ( int  spacing)

This function sets both the vertical and horizontal spacing to spacing.

See also
spacing(), setVerticalSpacing(), setHorizontalSpacing()
void QGridLayout::setVerticalSpacing ( int  spacing)

Property documentation pending.

QSize QGridLayout::sizeHint ( ) const
overridevirtual

Reimplemented from QLayoutItem::sizeHint().

Implements QLayoutItem.

int QGridLayout::spacing ( ) const

If the vertical spacing is equal to the horizontal spacing, this value is returned, otherwise it returns -1.

See also
setSpacing(), verticalSpacing(), horizontalSpacing()
QLayoutItem * QGridLayout::takeAt ( int  index)
overridevirtual

Reimplemented from QLayout::takeAt().

Implements QLayout.

int QGridLayout::verticalSpacing ( ) const

Property documentation pending.

Property Documentation

QGridLayout::horizontalSpacing

This property holds the spacing between widgets that are laid out side by side. If no value is explicitly set, the layout's horizontal spacing is inherited from the parent layout, or from the style settings for the parent widget.

See also
verticalSpacing, QStyle::pixelMetric(), PM_LayoutHorizontalSpacing
PropertiesClass Methods
read horizontalSpacing
write setHorizontalSpacing
QGridLayout::verticalSpacing

This property holds the spacing between widgets that are laid out on top of each other. If no value is explicitly set, the layout's vertical spacing is inherited from the parent layout, or from the style settings for the parent widget.

See also
horizontalSpacing, QStyle::pixelMetric(), PM_LayoutHorizontalSpacing
PropertiesClass Methods
read verticalSpacing
write setVerticalSpacing