Contents

• Public Types
• Properties
• Public Functions
• Reimplemented Public Functions
• Detailed Description

Detailed Description

TheQFormLayout class manages forms of input widgets and their associated labels.

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 usingQGridLayout.QFormLayout is a higher-level alternative that provides the following advantages:

• Adherence to the different platform's look and feel guidelines.

  For example, theMac OS X 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 towrap long rows, or even towrap all rows.

• Convenient API for creating label--field pairs.

  TheaddRow() overload that takes aQString and aQWidget * creates aQLabel behind the scenes and automatically set up its buddy. We can then write code like this:

  QFormLayout*formLayout=newQFormLayout;formLayout->addRow(tr("&Name:"), nameLineEdit);formLayout->addRow(tr("&Email:"), emailLineEdit);formLayout->addRow(tr("&Age:"), ageSpinBox);setLayout(formLayout);

  Compare this with the following code, written usingQGridLayout:

  nameLabel=newQLabel(tr("&Name:"));nameLabel->setBuddy(nameLineEdit);emailLabel=newQLabel(tr("&Name:"));emailLabel->setBuddy(emailLineEdit);ageLabel=newQLabel(tr("&Name:"));ageLabel->setBuddy(ageSpinBox);QGridLayout*gridLayout=newQGridLayout;gridLayout->addWidget(nameLabel,0,0);gridLayout->addWidget(nameLineEdit,0,1);gridLayout->addWidget(emailLabel,1,0);gridLayout->addWidget(emailLineEdit,1,1);gridLayout->addWidget(ageLabel,2,0);gridLayout->addWidget(ageSpinBox,2,1);setLayout(gridLayout);

The table below shows the default appearance in different styles.

QCommonStyle derived styles (exceptQPlastiqueStyle)	QMacStyle	QPlastiqueStyle	Qt Extended styles
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-columnQGridLayout.)	Style based on theMac OS X Aqua guidelines. Labels are right-aligned, the fields don't grow beyond their size hint, and the form is horizontally centered.	Recommended style forKDE 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.

The form styles can be also be overridden individually by callingsetLabelAlignment(),setFormAlignment(),setFieldGrowthPolicy(), andsetRowWrapPolicy(). For example, to simulate the form layout appearance ofQMacStyle on all platforms, but with left-aligned labels, you could write:

formLayout->setRowWrapPolicy(QFormLayout::DontWrapRows);formLayout->setFieldGrowthPolicy(QFormLayout::FieldsStayAtSizeHint);formLayout->setFormAlignment(Qt::AlignHCenter|Qt::AlignTop);formLayout->setLabelAlignment(Qt::AlignLeft);

Member Type Documentation

enum QFormLayout::FieldGrowthPolicy

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

See alsofieldGrowthPolicy.

enum QFormLayout::ItemRole

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

See alsoitemAt() andgetItemPosition().

enum QFormLayout::RowWrapPolicy

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

See alsorowWrapPolicy.

Property Documentation

fieldGrowthPolicy :FieldGrowthPolicy

This property holds the way in which the form's fields grow.

The default value depends on the widget or application style. ForQMacStyle, the default isFieldsStayAtSizeHint; forQCommonStyle derived styles (like Plastique and Windows), the default isExpandingFieldsGrow; for Qt Extended styles, the default isAllNonFixedFieldsGrow.

If none of the fields can grow and the form is resized, extra space is distributed according to the currentform alignment.

Access functions:

See alsoformAlignment androwWrapPolicy.

formAlignment :Qt::Alignment

This property holds the alignment of the form layout's contents within the layout's geometry.

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

Access functions:

See alsolabelAlignment androwWrapPolicy.

horizontalSpacing :int

This property holds 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.

Access functions:

See alsoverticalSpacing,QStyle::pixelMetric(), andPM_LayoutHorizontalSpacing.

labelAlignment :Qt::Alignment

This property holds the horizontal alignment of the labels.

The default value depends on the widget or application style. ForQCommonStyle derived styles, except forQPlastiqueStyle, the default isQt::AlignLeft; for the other styles, the default isQt::AlignRight.

Access functions:

See alsoformAlignment.

rowWrapPolicy :RowWrapPolicy

This property holds the way in which the form's rows wrap.

The default value depends on the widget or application style. For Qt Extended styles andQS60Style, the default isWrapLongRows; for the other styles, the default isDontWrapRows.

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

Access functions:

See alsofieldGrowthPolicy.

verticalSpacing :int

This property holds 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.

Access functions:

See alsohorizontalSpacing,QStyle::pixelMetric(), andPM_LayoutHorizontalSpacing.

Member Function Documentation

QFormLayout::QFormLayout(QWidget * parent = 0)

Constructs a new form layout with the givenparent widget.

See alsoQWidget::setLayout().

QFormLayout::~QFormLayout()

Destroys the form layout.

[virtual]void QFormLayout::addItem(QLayoutItem * item)

Reimplemented fromQLayout::addItem().

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

Adds a new row to the bottom of this form layout, with the givenlabel andfield.

See alsoinsertRow().

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

This is an overloaded function.

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

This is an overloaded function.

This overload automatically creates aQLabel behind the scenes withlabelText as its text. Thefield is set as the newQLabel'sbuddy.

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

This is an overloaded function.

This overload automatically creates aQLabel behind the scenes withlabelText as its text.

void QFormLayout::addRow(QWidget * widget)

This is an overloaded function.

Adds the specifiedwidget at the end of this form layout. Thewidget spans both columns.

void QFormLayout::addRow(QLayout * layout)

This is an overloaded function.

Adds the specifiedlayout at the end of this form layout. Thelayout spans both columns.

[virtual]int QFormLayout::count() const

Reimplemented fromQLayout::count().

[virtual]Qt::Orientations QFormLayout::expandingDirections() const

Reimplemented fromQLayoutItem::expandingDirections().

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

Retrieves the row and role (column) of the item at the specifiedindex. Ifindex is out of bounds, *rowPtr is set to -1; otherwise the row is stored in *rowPtr and the role is stored in *rolePtr.

See alsoitemAt(),count(),getLayoutPosition(), andgetWidgetPosition().

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

Retrieves the row and role (column) of the specified childlayout. Iflayout 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.

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

Retrieves the row and role (column) of the specifiedwidget in the layout. Ifwidget 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 alsogetItemPosition() anditemAt().

[virtual]bool QFormLayout::hasHeightForWidth() const

Reimplemented fromQLayoutItem::hasHeightForWidth().

[virtual]int QFormLayout::heightForWidth(int width) const

Reimplemented fromQLayoutItem::heightForWidth().

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

Inserts a new row at positionrow in this form layout, with the givenlabel andfield. Ifrow is out of bounds, the new row is added at the end.

See alsoaddRow().

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

This is an overloaded function.

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

This is an overloaded function.

This overload automatically creates aQLabel behind the scenes withlabelText as its text. Thefield is set as the newQLabel'sbuddy.

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

This is an overloaded function.

This overload automatically creates aQLabel behind the scenes withlabelText as its text.

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

This is an overloaded function.

Inserts the specifiedwidget at positionrow in this form layout. Thewidget spans both columns. Ifrow is out of bounds, the widget is added at the end.

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

This is an overloaded function.

Inserts the specifiedlayout at positionrow in this form layout. Thelayout spans both columns. Ifrow is out of bounds, the widget is added at the end.

[virtual]void QFormLayout::invalidate()

Reimplemented fromQLayoutItem::invalidate().

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

Returns the layout item in the givenrow with the specifiedrole (column). Returns 0 if there is no such item.

See alsoQLayout::itemAt() andsetItem().

[virtual]QLayoutItem * QFormLayout::itemAt(int index) const

Reimplemented fromQLayout::itemAt().

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

Returns the label associated with the givenfield.

See alsoitemAt().

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

This is an overloaded function.

[virtual]QSize QFormLayout::minimumSize() const

Reimplemented fromQLayoutItem::minimumSize().

int QFormLayout::rowCount() const

Returns the number of rows in the form.

See alsoQLayout::count().

[virtual]void QFormLayout::setGeometry(constQRect & rect)

Reimplemented fromQLayoutItem::setGeometry().

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

Sets the item in the givenrow for the givenrole toitem, extending the layout with empty rows if necessary.

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

Warning: Do not use this function to add child layouts or child widget items. UsesetLayout() orsetWidget() instead.

See alsosetLayout().

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

Sets the sub-layout in the givenrow for the givenrole tolayout, extending the form layout with empty rows if necessary.

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

Note: For most applications,addRow() orinsertRow() should be used instead of setLayout().

See alsosetWidget().

void QFormLayout::setSpacing(int spacing)

This function sets both the vertical and horizontal spacing tospacing.

See alsospacing(),setVerticalSpacing(), andsetHorizontalSpacing().

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

Sets the widget in the givenrow for the givenrole towidget, extending the layout with empty rows if necessary.

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

Note: For most applications,addRow() orinsertRow() should be used instead of setWidget().

See alsosetLayout().

[virtual]QSize QFormLayout::sizeHint() const

Reimplemented fromQLayoutItem::sizeHint().

int QFormLayout::spacing() const

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

See alsosetSpacing(),verticalSpacing(), andhorizontalSpacing().

[virtual]QLayoutItem * QFormLayout::takeAt(int index)

Reimplemented fromQLayout::takeAt().