Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
QFormLayout Class Reference

The QFormLayout class manages forms of input widgets and their associated labels. More...

#include <qformlayout.h>

+ Inheritance diagram for QFormLayout:
+ Collaboration diagram for QFormLayout:

Classes

class  TakeRowResult
 Contains the result of a QFormLayout::takeRow() call. More...
 

Public Types

enum  FieldGrowthPolicy { FieldsStayAtSizeHint , ExpandingFieldsGrow , AllNonFixedFieldsGrow }
 This enum specifies the different policies that can be used to control the way in which the form's fields grow. More...
 
enum  RowWrapPolicy { DontWrapRows , WrapLongRows , WrapAllRows }
 This enum specifies the different policies that can be used to control the way in which the form's rows wrap. More...
 
enum  ItemRole { LabelRole = 0 , FieldRole = 1 , SpanningRole = 2 }
 This enum specifies the types of widgets (or other layout items) that may appear in a row. More...
 
- Public Types inherited from QLayout
enum  SizeConstraint {
  SetDefaultConstraint , SetNoConstraint , SetMinimumSize , SetFixedSize ,
  SetMaximumSize , SetMinAndMaxSize
}
 The possible values are: More...
 

Public Member Functions

 QFormLayout (QWidget *parent=nullptr)
 \variable QFormLayout::TakeRowResult::labelItem
 
 ~QFormLayout ()
 Destroys the form layout.
 
void setFieldGrowthPolicy (FieldGrowthPolicy policy)
 
FieldGrowthPolicy fieldGrowthPolicy () const
 
void setRowWrapPolicy (RowWrapPolicy policy)
 
RowWrapPolicy rowWrapPolicy () const
 
void setLabelAlignment (Qt::Alignment alignment)
 
Qt::Alignment labelAlignment () const
 
void setFormAlignment (Qt::Alignment alignment)
 
Qt::Alignment formAlignment () const
 
void setHorizontalSpacing (int spacing)
 
int horizontalSpacing () const
 
void setVerticalSpacing (int spacing)
 
int verticalSpacing () const
 
int spacing () const override
 If the vertical spacing is equal to the horizontal spacing, this function returns that value; otherwise it returns -1.
 
void setSpacing (int) override
 This function sets both the vertical and horizontal spacing to spacing.
 
void addRow (QWidget *label, QWidget *field)
 Adds a new row to the bottom of this form layout, with the given label and field.
 
void addRow (QWidget *label, QLayout *field)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
void addRow (const QString &labelText, QWidget *field)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.This overload automatically creates a QLabel behind the scenes with labelText as its text.
 
void addRow (const QString &labelText, QLayout *field)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.This overload automatically creates a QLabel behind the scenes with labelText as its text.
 
void addRow (QWidget *widget)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Adds the specified widget at the end of this form layout.
 
void addRow (QLayout *layout)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Adds the specified layout at the end of this form layout.
 
void insertRow (int row, QWidget *label, QWidget *field)
 Inserts a new row at position row in this form layout, with the given label and field.
 
void insertRow (int row, QWidget *label, QLayout *field)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
void insertRow (int row, const QString &labelText, QWidget *field)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.This overload automatically creates a QLabel behind the scenes with labelText as its text.
 
void insertRow (int row, const QString &labelText, QLayout *field)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.This overload automatically creates a QLabel behind the scenes with labelText as its text.
 
void insertRow (int row, QWidget *widget)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Inserts the specified widget at position row in this form layout.
 
void insertRow (int row, QLayout *layout)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Inserts the specified layout at position row in this form layout.
 
void removeRow (int row)
 
void removeRow (QWidget *widget)
 
void removeRow (QLayout *layout)
 
TakeRowResult takeRow (int row)
 
TakeRowResult takeRow (QWidget *widget)
 
TakeRowResult takeRow (QLayout *layout)
 
void setItem (int row, ItemRole role, QLayoutItem *item)
 Sets the item in the given row for the given role to item, extending the layout with empty rows if necessary.
 
void setWidget (int row, ItemRole role, QWidget *widget)
 Sets the widget in the given row for the given role to widget, extending the layout with empty rows if necessary.
 
void setLayout (int row, ItemRole role, QLayout *layout)
 Sets the sub-layout in the given row for the given role to layout, extending the form layout with empty rows if necessary.
 
void setRowVisible (int row, bool on)
 
void setRowVisible (QWidget *widget, bool on)
 
void setRowVisible (QLayout *layout, bool on)
 
bool isRowVisible (int row) const
 
bool isRowVisible (QWidget *widget) const
 
bool isRowVisible (QLayout *layout) const
 
QLayoutItemitemAt (int row, ItemRole role) const
 Returns the layout item in the given row with the specified role (column).
 
void getItemPosition (int index, int *rowPtr, ItemRole *rolePtr) const
 Retrieves the row and role (column) of the item at the specified index.
 
void getWidgetPosition (QWidget *widget, int *rowPtr, ItemRole *rolePtr) const
 Retrieves the row and role (column) of the specified widget in the layout.
 
void getLayoutPosition (QLayout *layout, int *rowPtr, ItemRole *rolePtr) const
 Retrieves the row and role (column) of the specified child layout.
 
QWidgetlabelForField (QWidget *field) const
 Returns the label associated with the given field.
 
QWidgetlabelForField (QLayout *field) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
void addItem (QLayoutItem *item) override
 \reimp
 
QLayoutItemitemAt (int index) const override
 \reimp
 
QLayoutItemtakeAt (int index) override
 \reimp
 
void setGeometry (const QRect &rect) override
 \reimp
 
QSize minimumSize () const override
 \reimp
 
QSize sizeHint () const override
 \reimp
 
void invalidate () override
 \reimp
 
bool hasHeightForWidth () const override
 \reimp
 
int heightForWidth (int width) const override
 \reimp
 
Qt::Orientations expandingDirections () const override
 \reimp
 
int count () const override
 \reimp
 
int rowCount () const
 Returns the number of rows in the form.
 
- Public Member Functions inherited from QLayout
 QLayout (QWidget *parent=nullptr)
 Constructs a new top-level QLayout, with parent parent.
 
 ~QLayout ()
 
void setContentsMargins (int left, int top, int right, int bottom)
 
void setContentsMargins (const QMargins &margins)
 
void unsetContentsMargins ()
 
void getContentsMargins (int *left, int *top, int *right, int *bottom) const
 
QMargins contentsMargins () const
 
QRect contentsRect () const
 
bool setAlignment (QWidget *w, Qt::Alignment alignment)
 Sets the alignment for widget w to alignment and returns true if w is found in this layout (not including child layouts); otherwise returns false.
 
bool setAlignment (QLayout *l, Qt::Alignment alignment)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Sets the alignment for the layout l to alignment and returns true if l is found in this layout (not including child layouts); otherwise returns false.
 
void setSizeConstraint (SizeConstraint)
 
SizeConstraint sizeConstraint () const
 
void setMenuBar (QWidget *w)
 Tells the geometry manager to place the menu bar widget at the top of parentWidget(), outside QWidget::contentsMargins().
 
QWidgetmenuBar () const
 Returns the menu bar set for this layout, or \nullptr if no menu bar is set.
 
QWidgetparentWidget () const
 Returns the parent widget of this layout, or \nullptr if this layout is not installed on any widget.
 
void invalidate () override
 \reimp
 
QRect geometry () const override
 \reimp
 
bool activate ()
 Redoes the layout for parentWidget() if necessary.
 
void update ()
 Updates the layout for parentWidget().
 
void addWidget (QWidget *w)
 Adds widget w to this layout in a manner specific to the layout.
 
void removeWidget (QWidget *w)
 Removes the widget widget from the layout.
 
void removeItem (QLayoutItem *)
 Removes the layout item item from the layout.
 
Qt::Orientations expandingDirections () const override
 Returns whether this layout can make use of more space than sizeHint().
 
QSize minimumSize () const override
 Returns the minimum size of this layout.
 
QSize maximumSize () const override
 Returns the maximum size of this layout.
 
virtual int indexOf (const QWidget *) const
 Searches for widget widget in this layout (not including child layouts).
 
virtual int indexOf (const QLayoutItem *) const
 
bool isEmpty () const override
 \reimp
 
QSizePolicy::ControlTypes controlTypes () const override
 \reimp
 
virtual QLayoutItemreplaceWidget (QWidget *from, QWidget *to, Qt::FindChildOptions options=Qt::FindChildrenRecursively)
 
int totalMinimumHeightForWidth (int w) const
 
int totalHeightForWidth (int w) const
 
QSize totalMinimumSize () const
 
QSize totalMaximumSize () const
 
QSize totalSizeHint () const
 
QLayoutlayout () override
 \reimp
 
void setEnabled (bool)
 Enables this layout if enable is true, otherwise disables it.
 
bool isEnabled () const
 Returns true if the layout is enabled; otherwise returns false.
 
void setAlignment (Qt::Alignment a)
 Sets the alignment of this item to alignment.
 
- Public Member Functions inherited from QObject
Q_INVOKABLE QObject (QObject *parent=nullptr)
 Constructs an object with parent object parent.
 
virtual ~QObject ()
 Destroys the object, deleting all its child objects.
 
virtual bool event (QEvent *event)
 This virtual function receives events to an object and should return true if the event e was recognized and processed.
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 Filters events if this object has been installed as an event filter for the watched object.
 
QString objectName () const
 
Q_WEAK_OVERLOAD void setObjectName (const QString &name)
 Sets the object's name to name.
 
void setObjectName (QAnyStringView name)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
QBindable< QStringbindableObjectName ()
 
bool isWidgetType () const
 Returns true if the object is a widget; otherwise returns false.
 
bool isWindowType () const
 Returns true if the object is a window; otherwise returns false.
 
bool isQuickItemType () const
 Returns true if the object is a QQuickItem; otherwise returns false.
 
bool signalsBlocked () const noexcept
 Returns true if signals are blocked; otherwise returns false.
 
bool blockSignals (bool b) noexcept
 If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).
 
QThreadthread () const
 Returns the thread in which the object lives.
 
bool moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
 Changes the thread affinity for this object and its children and returns true on success.
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.
 
int startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)
 
void killTimer (int id)
 Kills the timer with timer identifier, id.
 
void killTimer (Qt::TimerId id)
 
template<typename T >
findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.
 
template<typename T >
QList< T > findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.
 
template<typename T >
findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
template<typename T >
QList< T > findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
const QObjectListchildren () const
 Returns a list of child objects.
 
void setParent (QObject *parent)
 Makes the object a child of parent.
 
void installEventFilter (QObject *filterObj)
 Installs an event filter filterObj on this object.
 
void removeEventFilter (QObject *obj)
 Removes an event filter object obj from this object.
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
 
bool disconnect (const char *signal=nullptr, const QObject *receiver=nullptr, const char *member=nullptr) const
 
bool disconnect (const QObject *receiver, const char *member=nullptr) const
 
void dumpObjectTree () const
 Dumps a tree of children to the debug output.
 
void dumpObjectInfo () const
 Dumps information about signal connections, etc.
 
bool setProperty (const char *name, const QVariant &value)
 Sets the value of the object's name property to value.
 
bool setProperty (const char *name, QVariant &&value)
 
QVariant property (const char *name) const
 Returns the value of the object's name property.
 
QList< QByteArraydynamicPropertyNames () const
 
QBindingStoragebindingStorage ()
 
const QBindingStoragebindingStorage () const
 
QObjectparent () const
 Returns a pointer to the parent object.
 
bool inherits (const char *classname) const
 Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false.
 
- Public Member Functions inherited from QLayoutItem
 QLayoutItem (Qt::Alignment alignment=Qt::Alignment())
 Constructs a layout item with an alignment.
 
virtual ~QLayoutItem ()
 Destroys the QLayoutItem.
 
virtual int minimumHeightForWidth (int) const
 Returns the minimum height this widget needs for the given width, w.
 
virtual QWidgetwidget () const
 If this item manages a QWidget, returns that widget.
 
virtual QSpacerItemspacerItem ()
 If this item is a QSpacerItem, it is returned as a QSpacerItem; otherwise \nullptr is returned.
 
Qt::Alignment alignment () const
 Returns the alignment of this item.
 
void setAlignment (Qt::Alignment a)
 Sets the alignment of this item to alignment.
 

Properties

FieldGrowthPolicy fieldGrowthPolicy
 the way in which the form's fields grow
 
RowWrapPolicy rowWrapPolicy
 the way in which the form's rows wrap
 
Qt::Alignment labelAlignment
 the horizontal alignment of the labels
 
Qt::Alignment formAlignment
 the alignment of the form layout's contents within the layout's geometry
 
int horizontalSpacing
 the spacing between widgets that are laid out side by side
 
int verticalSpacing
 the spacing between widgets that are laid out vertically
 
- Properties inherited from QLayout
int spacing
 the spacing between widgets inside the layout
 
QMargins contentsMargins
 
SizeConstraint sizeConstraint
 the resize mode of the layout
 
- Properties inherited from QObject
QString objectName
 the name of this object
 

Additional Inherited Members

- Public Slots inherited from QObject
void deleteLater ()
 \threadsafe
 
- Signals inherited from QObject
void destroyed (QObject *=nullptr)
 This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.
 
void objectNameChanged (const QString &objectName, QPrivateSignal)
 This signal is emitted after the object's name has been changed.
 
- Static Public Member Functions inherited from QLayout
static QSize closestAcceptableSize (const QWidget *w, const QSize &s)
 Returns a size that satisfies all size constraints on widget, including heightForWidth() and that is as close as possible to size.
 
- Static Public Member Functions inherited from QObject
static QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
 \threadsafe
 
static QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
 
template<typename Func1 , typename Func2 >
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType *context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)
 
template<typename Func1 , typename Func2 >
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)
 
static bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
 \threadsafe
 
static bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
 
static bool disconnect (const QMetaObject::Connection &)
 Disconnect a connection.
 
template<typename Func1 , typename Func2 >
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object *receiver, Func2 slot)
 
template<typename Func1 >
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const QObject *receiver, void **zero)
 
- Protected Member Functions inherited from QLayout
void widgetEvent (QEvent *)
 
void childEvent (QChildEvent *e) override
 \reimp
 
void addChildLayout (QLayout *l)
 This function is called from addLayout() or insertLayout() functions in subclasses to add layout childLayout as a sub-layout.
 
void addChildWidget (QWidget *w)
 This function is called from addWidget() functions in subclasses to add w as a managed widget of a layout.
 
bool adoptLayout (QLayout *layout)
 
QRect alignmentRect (const QRect &) const
 Returns the rectangle that should be covered when the geometry of this layout is set to r, provided that this layout supports setAlignment().
 
 QLayout (QLayoutPrivate &d, QLayout *, QWidget *)
 
- Protected Member Functions inherited from QObject
QObjectsender () const
 Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.
 
int senderSignalIndex () const
 
int receivers (const char *signal) const
 Returns the number of receivers connected to the signal.
 
bool isSignalConnected (const QMetaMethod &signal) const
 
virtual void timerEvent (QTimerEvent *event)
 This event handler can be reimplemented in a subclass to receive timer events for the object.
 
virtual void customEvent (QEvent *event)
 This event handler can be reimplemented in a subclass to receive custom events.
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
 QObject (QObjectPrivate &dd, QObject *parent=nullptr)
 
- Protected Attributes inherited from QObject
QScopedPointer< QObjectDatad_ptr
 
- Protected Attributes inherited from QLayoutItem
Qt::Alignment align
 

Detailed Description

The QFormLayout class manages forms of input widgets and their associated labels.

Since
4.4

\inmodule QtWidgets

QFormLayout is a convenience layout class that lays out its children in a two-column form. The left column consists of labels and the right column consists of "field" widgets (line editors, spin boxes, etc.).

Traditionally, such two-column form layouts were achieved using QGridLayout. QFormLayout is a higher-level alternative that provides the following advantages:

\list

  • {Adherence to the different platform's look and feel guidelines.}
    For example, the
    \l{http://developer.apple.com/library/mac/#documentation/UserExperience/Conceptual/AppleHIGuidelines/Intro/Intro.html}{\macos Aqua} and KDE guidelines specify that the
    labels should be right-aligned, whereas Windows and GNOME
    applications normally use left-alignment.
    
  • {Support for wrapping long rows.}

For devices with small displays, QFormLayout can be set to \l{WrapLongRows}{wrap long rows}, or even to \l{WrapAllRows}{wrap all rows}.

  • {Convenient API for creating label–field pairs.}

The addRow() overload that takes a QString and a QWidget * creates a QLabel behind the scenes and automatically set up its buddy. We can then write code like this:

formLayout->addRow(tr("&Name:"), nameLineEdit);
formLayout->addRow(tr("&Email:"), emailLineEdit);

Compare this with the following code, written using QGridLayout:

nameLabel = new QLabel(tr("&Name:"));
nameLabel->setBuddy(nameLineEdit);
emailLabel = new QLabel(tr("&Name:"));
emailLabel->setBuddy(emailLineEdit);
ageLabel = new QLabel(tr("&Name:"));
ageLabel->setBuddy(ageSpinBox);
gridLayout->addWidget(nameLineEdit, 0, 1);
gridLayout->addWidget(emailLineEdit, 1, 1);

\endlist

The table below shows the default appearance in different styles.

\table \header

  • QCommonStyle derived styles (except QPlastiqueStyle)
  • QMacStyle
  • QPlastiqueStyle
  • Qt Extended styles \row
  • \inlineimage qformlayout-win.png
  • \inlineimage qformlayout-mac.png
  • \inlineimage qformlayout-kde.png
  • \inlineimage qformlayout-qpe.png \row
  • Traditional style used for Windows, GNOME, and earlier versions of KDE. Labels are left aligned, and expanding fields grow to fill the available space. (This normally corresponds to what we would get using a two-column QGridLayout.)
  • Style based on the \l{http://developer.apple.com/library/mac/#documentation/UserExperience/Conceptual/AppleHIGuidelines/Intro/Intro.html}{\macos Aqua} guidelines. Labels are right-aligned, the fields don't grow beyond their size hint, and the form is horizontally centered.
  • Recommended style for \l{KDE applications}. Similar to MacStyle, except that the form is left-aligned and all fields grow to fill the available space.
  • Default style for Qt Extended styles. Labels are right-aligned, expanding fields grow to fill the available space, and row wrapping is enabled for long lines. \endtable

The form styles can be also be overridden individually by calling setLabelAlignment(), setFormAlignment(), setFieldGrowthPolicy(), and setRowWrapPolicy(). For example, to simulate the form layout appearance of QMacStyle on all platforms, but with left-aligned labels, you could write:

See also
QGridLayout, QBoxLayout, QStackedLayout

Definition at line 17 of file qformlayout.h.

Member Enumeration Documentation

◆ FieldGrowthPolicy

This enum specifies the different policies that can be used to control the way in which the form's fields grow.

\value FieldsStayAtSizeHint The fields never grow beyond their \l{QWidgetItem::sizeHint()}{effective size hint}. This is the default for QMacStyle.

\value ExpandingFieldsGrow Fields with an horizontal \l{QSizePolicy}{size policy} of \l{QSizePolicy::}{Expanding} or \l{QSizePolicy::}{MinimumExpanding} will grow to fill the available space. The other fields will not grow beyond their effective size hint. This is the default policy for Plastique.

\value AllNonFixedFieldsGrow All fields with a size policy that allows them to grow will grow to fill the available space. This is the default policy for most styles.

See also
fieldGrowthPolicy
Enumerator
FieldsStayAtSizeHint 
ExpandingFieldsGrow 
AllNonFixedFieldsGrow 

Definition at line 33 of file qformlayout.h.

◆ ItemRole

This enum specifies the types of widgets (or other layout items) that may appear in a row.

\value LabelRole A label widget. \value FieldRole A field widget. \value SpanningRole A widget that spans label and field columns.

See also
itemAt(), getItemPosition()
Enumerator
LabelRole 
FieldRole 
SpanningRole 

Definition at line 47 of file qformlayout.h.

◆ RowWrapPolicy

This enum specifies the different policies that can be used to control the way in which the form's rows wrap.

\value DontWrapRows Fields are always laid out next to their label. This is the default policy for all styles except Qt Extended styles.

\value WrapLongRows Labels are given enough horizontal space to fit the widest label, and the rest of the space is given to the fields. If the minimum size of a field pair is wider than the available space, the field is wrapped to the next line. This is the default policy for Qt Extended styles.

\value WrapAllRows Fields are always laid out below their label.

See also
rowWrapPolicy
Enumerator
DontWrapRows 
WrapLongRows 
WrapAllRows 

Definition at line 40 of file qformlayout.h.

Constructor & Destructor Documentation

◆ QFormLayout()

QFormLayout::QFormLayout ( QWidget * parent = nullptr)
explicit

\variable QFormLayout::TakeRowResult::labelItem

Contains the layout item corresponding to the label of the row.

\variable QFormLayout::TakeRowResult::fieldItem

Contains the layout item corresponding to the field of the row.

Constructs a new form layout with the given parent widget.

The layout is set directly as the top-level layout for parent. There can be only one top-level layout for a widget. It is returned by QWidget::layout().

See also
QWidget::setLayout()

Definition at line 1204 of file qformlayout.cpp.

◆ ~QFormLayout()

QFormLayout::~QFormLayout ( )

Destroys the form layout.

Definition at line 1212 of file qformlayout.cpp.

Member Function Documentation

◆ addItem()

void QFormLayout::addItem ( QLayoutItem * item)
overridevirtual

\reimp

Implements QLayout.

Definition at line 1640 of file qformlayout.cpp.

◆ addRow() [1/6]

void QFormLayout::addRow ( const QString & labelText,
QLayout * field )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.This overload automatically creates a QLabel behind the scenes with labelText as its text.

Definition at line 1263 of file qformlayout.cpp.

◆ addRow() [2/6]

void QFormLayout::addRow ( const QString & labelText,
QWidget * field )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.This overload automatically creates a QLabel behind the scenes with labelText as its text.

The field is set as the new QLabel's \l{QLabel::setBuddy()}{buddy}.

Definition at line 1252 of file qformlayout.cpp.

◆ addRow() [3/6]

void QFormLayout::addRow ( QLayout * layout)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Adds the specified layout at the end of this form layout.

The layout spans both columns.

Definition at line 1285 of file qformlayout.cpp.

◆ addRow() [4/6]

void QFormLayout::addRow ( QWidget * label,
QLayout * field )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 1240 of file qformlayout.cpp.

◆ addRow() [5/6]

void QFormLayout::addRow ( QWidget * label,
QWidget * field )

Adds a new row to the bottom of this form layout, with the given label and field.

See also
insertRow()

Definition at line 1232 of file qformlayout.cpp.

◆ addRow() [6/6]

void QFormLayout::addRow ( QWidget * widget)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Adds the specified widget at the end of this form layout.

The widget spans both columns.

Definition at line 1274 of file qformlayout.cpp.

◆ count()

int QFormLayout::count ( ) const
overridevirtual

\reimp

Implements QLayout.

Definition at line 1652 of file qformlayout.cpp.

◆ expandingDirections()

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

\reimp

Implements QLayoutItem.

Definition at line 1699 of file qformlayout.cpp.

◆ fieldGrowthPolicy()

QFormLayout::FieldGrowthPolicy QFormLayout::fieldGrowthPolicy ( ) const

Definition at line 1989 of file qformlayout.cpp.

◆ formAlignment()

Qt::Alignment QFormLayout::formAlignment ( ) const

Definition at line 2083 of file qformlayout.cpp.

◆ getItemPosition()

void QFormLayout::getItemPosition ( int index,
int * rowPtr,
ItemRole * rolePtr ) const

Retrieves the row and role (column) of the item at the specified index.

If index is out of bounds, *rowPtr is set to -1; otherwise the row is stored in *rowPtr and the role is stored in *rolePtr.

See also
itemAt(), count(), getLayoutPosition(), getWidgetPosition()

Definition at line 1868 of file qformlayout.cpp.

◆ getLayoutPosition()

void QFormLayout::getLayoutPosition ( QLayout * layout,
int * rowPtr,
ItemRole * rolePtr ) const

Retrieves the row and role (column) of the specified child layout.

If layout is not in the form layout, *rowPtr is set to -1; otherwise the row is stored in *rowPtr and the role is stored in *rolePtr.

Definition at line 1896 of file qformlayout.cpp.

◆ getWidgetPosition()

void QFormLayout::getWidgetPosition ( QWidget * widget,
int * rowPtr,
ItemRole * rolePtr ) const

Retrieves the row and role (column) of the specified widget in the layout.

If widget is not in the layout, *rowPtr is set to -1; otherwise the row is stored in *rowPtr and the role is stored in *rolePtr.

See also
getItemPosition(), itemAt()

Definition at line 1916 of file qformlayout.cpp.

◆ hasHeightForWidth()

bool QFormLayout::hasHeightForWidth ( ) const
overridevirtual

\reimp

Reimplemented from QLayoutItem.

Definition at line 1716 of file qformlayout.cpp.

◆ heightForWidth()

int QFormLayout::heightForWidth ( int width) const
overridevirtual

\reimp

Reimplemented from QLayoutItem.

Definition at line 1727 of file qformlayout.cpp.

◆ horizontalSpacing()

int QFormLayout::horizontalSpacing ( ) const

Definition at line 2112 of file qformlayout.cpp.

◆ insertRow() [1/6]

void QFormLayout::insertRow ( int row,
const QString & labelText,
QLayout * field )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.This overload automatically creates a QLabel behind the scenes with labelText as its text.

Definition at line 1357 of file qformlayout.cpp.

◆ insertRow() [2/6]

void QFormLayout::insertRow ( int row,
const QString & labelText,
QWidget * field )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.This overload automatically creates a QLabel behind the scenes with labelText as its text.

The field is set as the new QLabel's \l{QLabel::setBuddy()}{buddy}.

Definition at line 1335 of file qformlayout.cpp.

◆ insertRow() [3/6]

void QFormLayout::insertRow ( int row,
QLayout * layout )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Inserts the specified layout at position row in this form layout.

The layout spans both columns. If row is out of bounds, the widget is added at the end.

Definition at line 1391 of file qformlayout.cpp.

◆ insertRow() [4/6]

void QFormLayout::insertRow ( int row,
QWidget * label,
QLayout * field )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 1314 of file qformlayout.cpp.

◆ insertRow() [5/6]

void QFormLayout::insertRow ( int row,
QWidget * label,
QWidget * field )

Inserts a new row at position row in this form layout, with the given label and field.

If row is out of bounds, the new row is added at the end.

See also
addRow()

Definition at line 1297 of file qformlayout.cpp.

◆ insertRow() [6/6]

void QFormLayout::insertRow ( int row,
QWidget * widget )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Inserts the specified widget at position row in this form layout.

The widget spans both columns. If row is out of bounds, the widget is added at the end.

Definition at line 1373 of file qformlayout.cpp.

◆ invalidate()

void QFormLayout::invalidate ( )
overridevirtual

\reimp

Reimplemented from QLayoutItem.

Definition at line 1808 of file qformlayout.cpp.

◆ isRowVisible() [1/3]

bool QFormLayout::isRowVisible ( int row) const
Since
6.4

Returns true if some items in the row row are visible, otherwise returns false.

Definition at line 2400 of file qformlayout.cpp.

◆ isRowVisible() [2/3]

bool QFormLayout::isRowVisible ( QLayout * layout) const
Since
6.4 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns true if some items in the row corresponding to layout are visible, otherwise returns false.

Definition at line 2446 of file qformlayout.cpp.

◆ isRowVisible() [3/3]

bool QFormLayout::isRowVisible ( QWidget * widget) const
Since
6.4 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns true if some items in the row corresponding to widget are visible, otherwise returns false.

Definition at line 2422 of file qformlayout.cpp.

◆ itemAt() [1/2]

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

\reimp

Implements QLayout.

Definition at line 1661 of file qformlayout.cpp.

◆ itemAt() [2/2]

QLayoutItem * QFormLayout::itemAt ( int row,
ItemRole role ) const

Returns the layout item in the given row with the specified role (column).

Returns \nullptr if there is no such item.

See also
QLayout::itemAt(), setItem()

Definition at line 1840 of file qformlayout.cpp.

◆ labelAlignment()

Qt::Alignment QFormLayout::labelAlignment ( ) const

Definition at line 2053 of file qformlayout.cpp.

◆ labelForField() [1/2]

QWidget * QFormLayout::labelForField ( QLayout * field) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 1947 of file qformlayout.cpp.

◆ labelForField() [2/2]

QWidget * QFormLayout::labelForField ( QWidget * field) const

Returns the label associated with the given field.

See also
itemAt()

Definition at line 1928 of file qformlayout.cpp.

◆ minimumSize()

QSize QFormLayout::minimumSize ( ) const
overridevirtual

\reimp

Implements QLayoutItem.

Definition at line 1794 of file qformlayout.cpp.

◆ removeRow() [1/3]

void QFormLayout::removeRow ( int row)
Since
5.8

Deletes row row from this form layout.

row must be non-negative and less than rowCount().

After this call, rowCount() is decremented by one. All widgets and nested layouts that occupied this row are deleted. That includes both the field widget(s) and the label, if any. All following rows are shifted up one row and the freed vertical space is redistributed amongst the remaining rows.

You can use this function to undo a previous addRow() or insertRow():

flay->insertRow(2, "User:", le);
// later:
flay->removeRow(2); // le == nullptr at this point

If you want to remove the row from the layout without deleting the widgets, use takeRow() instead.

See also
takeRow()

Definition at line 1452 of file qformlayout.cpp.

◆ removeRow() [2/3]

void QFormLayout::removeRow ( QLayout * layout)
Since
5.8

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Deletes the row corresponding to layout from this form layout.

After this call, rowCount() is decremented by one. All widgets and nested layouts that occupied this row are deleted. That includes both the field widget(s) and the label, if any. All following rows are shifted up one row and the freed vertical space is redistributed amongst the remaining rows.

You can use this function to undo a previous addRow() or insertRow():

flay->insertRow(2, "User:", vbl);
// later:
flay->removeRow(layout); // vbl == nullptr at this point

If you want to remove the row from the form layout without deleting the inserted layout, use takeRow() instead.

See also
takeRow()

Definition at line 1505 of file qformlayout.cpp.

◆ removeRow() [3/3]

void QFormLayout::removeRow ( QWidget * widget)
Since
5.8

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Deletes the row corresponding to widget from this form layout.

After this call, rowCount() is decremented by one. All widgets and nested layouts that occupied this row are deleted. That includes both the field widget(s) and the label, if any. All following rows are shifted up one row and the freed vertical space is redistributed amongst the remaining rows.

You can use this function to undo a previous addRow() or insertRow():

flay->insertRow(2, "User:", le);
// later:
flay->removeRow(le); // le == nullptr at this point

If you want to remove the row from the layout without deleting the widgets, use takeRow() instead.

See also
takeRow()

Definition at line 1478 of file qformlayout.cpp.

◆ rowCount()

int QFormLayout::rowCount ( ) const

Returns the number of rows in the form.

See also
QLayout::count()

Definition at line 1828 of file qformlayout.cpp.

◆ rowWrapPolicy()

QFormLayout::RowWrapPolicy QFormLayout::rowWrapPolicy ( ) const

Definition at line 2022 of file qformlayout.cpp.

◆ setFieldGrowthPolicy()

void QFormLayout::setFieldGrowthPolicy ( FieldGrowthPolicy policy)

Definition at line 1980 of file qformlayout.cpp.

◆ setFormAlignment()

void QFormLayout::setFormAlignment ( Qt::Alignment alignment)

Definition at line 2074 of file qformlayout.cpp.

◆ setGeometry()

void QFormLayout::setGeometry ( const QRect & rect)
overridevirtual

\reimp

Reimplemented from QLayout.

Definition at line 1753 of file qformlayout.cpp.

◆ setHorizontalSpacing()

void QFormLayout::setHorizontalSpacing ( int spacing)

Definition at line 2103 of file qformlayout.cpp.

◆ setItem()

void QFormLayout::setItem ( int row,
ItemRole role,
QLayoutItem * item )

Sets the item in the given row for the given role to item, extending the layout with empty rows if necessary.

If the cell is already occupied, the item is not inserted and an error message is sent to the console. The item spans both columns.

Warning
Do not use this function to add child layouts or child widget items. Use setLayout() or setWidget() instead.
See also
setLayout()

Definition at line 2302 of file qformlayout.cpp.

◆ setLabelAlignment()

void QFormLayout::setLabelAlignment ( Qt::Alignment alignment)

Definition at line 2044 of file qformlayout.cpp.

◆ setLayout()

void QFormLayout::setLayout ( int row,
ItemRole role,
QLayout * layout )

Sets the sub-layout in the given row for the given role to layout, extending the form layout with empty rows if necessary.

If the cell is already occupied, the layout is not inserted and an error message is sent to the console.

{Note:} For most applications, addRow() or insertRow() should be used instead of setLayout().

See also
setWidget()

Definition at line 2280 of file qformlayout.cpp.

◆ setRowVisible() [1/3]

void QFormLayout::setRowVisible ( int row,
bool on )
Since
6.4

Shows the row row if on is true, otherwise hides the row.

row must be non-negative and less than rowCount().

See also
removeRow(), takeRow()

Definition at line 2320 of file qformlayout.cpp.

◆ setRowVisible() [2/3]

void QFormLayout::setRowVisible ( QLayout * layout,
bool on )
Since
6.4

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Shows the row corresponding to layout if on is true, otherwise hides the row.

See also
removeRow(), takeRow()

Definition at line 2376 of file qformlayout.cpp.

◆ setRowVisible() [3/3]

void QFormLayout::setRowVisible ( QWidget * widget,
bool on )
Since
6.4

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Shows the row corresponding to widget if on is true, otherwise hides the row.

See also
removeRow(), takeRow()

Definition at line 2348 of file qformlayout.cpp.

◆ setRowWrapPolicy()

void QFormLayout::setRowWrapPolicy ( RowWrapPolicy policy)

Definition at line 2013 of file qformlayout.cpp.

◆ setSpacing()

void QFormLayout::setSpacing ( int spacing)
overridevirtual

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

See also
setVerticalSpacing(), setHorizontalSpacing()

Reimplemented from QLayout.

Definition at line 2157 of file qformlayout.cpp.

◆ setVerticalSpacing()

void QFormLayout::setVerticalSpacing ( int spacing)

Definition at line 2132 of file qformlayout.cpp.

◆ setWidget()

void QFormLayout::setWidget ( int row,
ItemRole role,
QWidget * widget )

Sets the widget in the given row for the given role to widget, extending the layout with empty rows if necessary.

If the cell is already occupied, the widget is not inserted and an error message is sent to the console.

{Note:} For most applications, addRow() or insertRow() should be used instead of setWidget().

See also
setLayout()

Definition at line 2260 of file qformlayout.cpp.

◆ sizeHint()

QSize QFormLayout::sizeHint ( ) const
overridevirtual

\reimp

Implements QLayoutItem.

Definition at line 1781 of file qformlayout.cpp.

◆ spacing()

int QFormLayout::spacing ( ) const
overridevirtual

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

See also
setSpacing(), verticalSpacing(), horizontalSpacing()

Reimplemented from QLayout.

Definition at line 2170 of file qformlayout.cpp.

◆ takeAt()

QLayoutItem * QFormLayout::takeAt ( int index)
overridevirtual

\reimp

Implements QLayout.

Definition at line 1672 of file qformlayout.cpp.

◆ takeRow() [1/3]

QFormLayout::TakeRowResult QFormLayout::takeRow ( int row)
Since
5.8

Removes the specified row from this form layout.

row must be non-negative and less than rowCount().

Note
This function doesn't delete anything.

After this call, rowCount() is decremented by one. All following rows are shifted up one row and the freed vertical space is redistributed amongst the remaining rows.

You can use this function to undo a previous addRow() or insertRow():

If you want to remove the row from the layout and delete the widgets, use removeRow() instead.

Returns
A structure containing both the widget and corresponding label layout items
See also
removeRow()

Definition at line 1534 of file qformlayout.cpp.

◆ takeRow() [2/3]

QFormLayout::TakeRowResult QFormLayout::takeRow ( QLayout * layout)
Since
5.8

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Removes the specified layout from this form layout.

Note
This function doesn't delete anything.

After this call, rowCount() is decremented by one. All following rows are shifted up one row and the freed vertical space is redistributed amongst the remaining rows.

flay->insertRow(2, "User:", vbl);
// later:
The QFormLayout class manages forms of input widgets and their associated labels.
Definition qformlayout.h:18
TakeRowResult takeRow(int row)
void setRowWrapPolicy(RowWrapPolicy policy)
void setFieldGrowthPolicy(FieldGrowthPolicy policy)
void setFormAlignment(Qt::Alignment alignment)
void insertRow(int row, QWidget *label, QWidget *field)
Inserts a new row at position row in this form layout, with the given label and field.
void addRow(QWidget *label, QWidget *field)
Adds a new row to the bottom of this form layout, with the given label and field.
void setLabelAlignment(Qt::Alignment alignment)
void removeRow(int row)
@ FieldsStayAtSizeHint
Definition qformlayout.h:34
@ AlignHCenter
Definition qnamespace.h:149
QFormLayout * formLayout
[0]
QPointer< QVBoxLayout > vbl
QGridLayout * gridLayout
[0]
QFormLayout * flay
[2]
QPointer< QLineEdit > le
Contains the result of a QFormLayout::takeRow() call.
Definition qformlayout.h:54

If you want to remove the row from the form layout and delete the inserted layout, use removeRow() instead.

Returns
A structure containing both the widget and corresponding label layout items
See also
removeRow()

Definition at line 1619 of file qformlayout.cpp.

◆ takeRow() [3/3]

QFormLayout::TakeRowResult QFormLayout::takeRow ( QWidget * widget)
Since
5.8

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Removes the specified widget from this form layout.

Note
This function doesn't delete anything.

After this call, rowCount() is decremented by one. All following rows are shifted up one row and the freed vertical space is redistributed amongst the remaining rows.

If you want to remove the row from the layout and delete the widgets, use removeRow() instead.

Returns
A structure containing both the widget and corresponding label layout items
See also
removeRow()

Definition at line 1579 of file qformlayout.cpp.

◆ verticalSpacing()

int QFormLayout::verticalSpacing ( ) const

Definition at line 2141 of file qformlayout.cpp.

Property Documentation

◆ fieldGrowthPolicy

FieldGrowthPolicy QFormLayout::fieldGrowthPolicy
readwrite

the way in which the form's fields grow

The default value depends on the widget or application style. For QMacStyle, the default is FieldsStayAtSizeHint; for QCommonStyle derived styles (like Plastique and Windows), the default is ExpandingFieldsGrow; for Qt Extended styles, the default is AllNonFixedFieldsGrow.

If none of the fields can grow and the form is resized, extra space is distributed according to the current \l{formAlignment}{form alignment}.

See also
formAlignment, rowWrapPolicy

Definition at line 21 of file qformlayout.h.

◆ formAlignment

Qt::Alignment QFormLayout::formAlignment
readwrite

the alignment of the form layout's contents within the layout's geometry

The default value depends on the widget or application style. For QMacStyle, the default is Qt::AlignHCenter | Qt::AlignTop; for the other styles, the default is Qt::AlignLeft | Qt::AlignTop.

See also
labelAlignment, rowWrapPolicy

Definition at line 27 of file qformlayout.h.

◆ horizontalSpacing

int QFormLayout::horizontalSpacing
readwrite

the spacing between widgets that are laid out side by side

By default, 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(), {QStyle::}{PM_LayoutHorizontalSpacing}

Definition at line 29 of file qformlayout.h.

◆ labelAlignment

Qt::Alignment QFormLayout::labelAlignment
readwrite

the horizontal alignment of the labels

The default value depends on the widget or application style. For QCommonStyle derived styles, except for QPlastiqueStyle, the default is Qt::AlignLeft; for the other styles, the default is Qt::AlignRight.

See also
formAlignment

Definition at line 25 of file qformlayout.h.

◆ rowWrapPolicy

RowWrapPolicy QFormLayout::rowWrapPolicy
readwrite

the way in which the form's rows wrap

The default value depends on the widget or application style. For Qt Extended styles, the default is WrapLongRows; for the other styles, the default is DontWrapRows.

If you want to display each label above its associated field (instead of next to it), set this property to WrapAllRows.

See also
fieldGrowthPolicy

Definition at line 23 of file qformlayout.h.

◆ verticalSpacing

int QFormLayout::verticalSpacing
readwrite

the spacing between widgets that are laid out vertically

By default, 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(), {QStyle::}{PM_LayoutHorizontalSpacing}

Definition at line 30 of file qformlayout.h.


The documentation for this class was generated from the following files: