com.trolltech.qt.gui
Class QFormLayout

java.lang.Object
  com.trolltech.qt.internal.QSignalEmitterInternal
      com.trolltech.qt.QSignalEmitter
          com.trolltech.qt.QtJambiObject
              com.trolltech.qt.core.QObject
                  com.trolltech.qt.gui.QLayout
                      com.trolltech.qt.gui.QFormLayout

All Implemented Interfaces:

QLayoutItemInterface, QtJambiInterface

public class QFormLayout
extends QLayout

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

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

  For example, the Mac 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 to wrap long rows , or even to 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:

          QFormLayout formLayout = new QFormLayout();
          formLayout.addRow(tr("Name:"), nameLineEdit);
          formLayout.addRow(tr("Email:"), emailLineEdit);
          formLayout.addRow(tr("Age:"), ageSpinBox);
          setLayout(formLayout);
  

  Compare this with the following code, written using QGridLayout:

          nameLabel = new QLabel(tr("Name:"));
          nameLabel.setBuddy(nameLineEdit);
  
          emailLabel = new QLabel(tr("Email:"));
          emailLabel.setBuddy(emailLineEdit);
  
          ageLabel = new QLabel(tr("Age:"));
          ageLabel.setBuddy(ageSpinBox);
  
          QGridLayout gridLayout = new QGridLayout();
          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 (except QPlastiqueStyle)	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-column QGridLayout.)	Style based on the Mac 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 for 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.

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:

        formLayout.setLabelAlignment(Qt.AlignmentFlag.AlignLeft);

See also:

QGridLayout, QBoxLayout, and QStackedLayout.

Nested Class Summary

static class	QFormLayout.FieldGrowthPolicy This enum specifies the different policies that can be used to control the way in which the form's fields grow.
static class	QFormLayout.ItemRole This enum specifies the types of widgets (or other layout items) that may appear in a row.
static class	QFormLayout.RowWrapPolicy This enum specifies the different policies that can be used to control the way in which the form's rows wrap.

Nested classes/interfaces inherited from class com.trolltech.qt.gui.QLayout

QLayout.SizeConstraint

Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter

QSignalEmitter.AbstractSignal, QSignalEmitter.PrivateSignal0, QSignalEmitter.PrivateSignal1, QSignalEmitter.PrivateSignal2, QSignalEmitter.PrivateSignal3, QSignalEmitter.PrivateSignal4, QSignalEmitter.PrivateSignal5, QSignalEmitter.PrivateSignal6, QSignalEmitter.PrivateSignal7, QSignalEmitter.PrivateSignal8, QSignalEmitter.PrivateSignal9, QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9

Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal

com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal

Field Summary

Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal

currentSender

Constructor Summary

QFormLayout()
Constructs a new form layout with the given parent widget.

QFormLayout(QWidget parent)
Constructs a new form layout with the given parent widget.

Method Summary

void	addRow(QLayout layout) This is an overloaded member function, provided for convenience.
void	addRow(QWidget widget) This is an overloaded member function, provided for convenience.
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(java.lang.String labelText, QLayout field) This is an overloaded member function, provided for convenience.
void	addRow(java.lang.String labelText, QWidget field) This is an overloaded member function, provided for convenience.
QFormLayout.FieldGrowthPolicy	fieldGrowthPolicy() This property holds the way in which the form's fields grow.
Qt.Alignment	formAlignment() This property holds the alignment of the form layout's contents within the layout's geometry.
QPair	getItemPosition(int index) Retrieves the row and role (column) of the item at the specified index.
QPair	getLayoutPosition(QLayout layout) Retrieves the row and role (column) of the specified child layout.
QPair	getWidgetPosition(QWidget widget) Retrieves the row and role (column) of the specified widget in the layout.
int	horizontalSpacing() This property holds the spacing between widgets that are laid out side by side.
void	insertRow(int row, QLayout layout) This is an overloaded member function, provided for convenience.
void	insertRow(int row, QWidget widget) This is an overloaded member function, provided for convenience.
void	insertRow(int row, QWidget label, QLayout field) Inserts a new row at position row in this form layout, with the given label and field.
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, java.lang.String labelText, QLayout field) This is an overloaded member function, provided for convenience.
void	insertRow(int row, java.lang.String labelText, QWidget field) This is an overloaded member function, provided for convenience.
QLayoutItemInterface	itemAt(int row, QFormLayout.ItemRole role) Returns the layout item in the given row with the specified role (column).
Qt.Alignment	labelAlignment() This property holds the horizontal alignment of the labels.
QWidget	labelForField(QLayout field) This is an overloaded member function, provided for convenience.
QWidget	labelForField(QWidget field) Returns the label associated with the given field.
int	rowCount() Returns the number of rows in the form.
QFormLayout.RowWrapPolicy	rowWrapPolicy() This property holds the way in which the form's rows wrap.
void	setFieldGrowthPolicy(QFormLayout.FieldGrowthPolicy policy) This property holds the way in which the form's fields grow.
void	setFormAlignment(Qt.Alignment alignment) This property holds the alignment of the form layout's contents within the layout's geometry.
void	setFormAlignment(Qt.AlignmentFlag[] alignment)
void	setHorizontalSpacing(int spacing) This property holds the spacing between widgets that are laid out side by side.
void	setItem(int row, QFormLayout.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	setLabelAlignment(Qt.Alignment alignment) This property holds the horizontal alignment of the labels.
void	setLabelAlignment(Qt.AlignmentFlag[] alignment)
void	setLayout(int row, QFormLayout.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	setRowWrapPolicy(QFormLayout.RowWrapPolicy policy) This property holds the way in which the form's rows wrap.
void	setSpacing(int arg__1) This function sets both the vertical and horizontal spacing to spacing.
void	setVerticalSpacing(int spacing) This property holds the spacing between widgets that are laid out vertically.
void	setWidget(int row, QFormLayout.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.
int	spacing() If the vertical spacing is equal to the horizontal spacing, this function returns that value; otherwise it returns -1.
int	verticalSpacing() This property holds the spacing between widgets that are laid out vertically.

Methods inherited from class com.trolltech.qt.gui.QLayout

activate, addChildLayout, addChildWidget, addItem, addWidget, alignment, alignmentRect, closestAcceptableSize, contentsRect, controlTypes, count, expandingDirections, geometry, getContentsMargins, hasHeightForWidth, heightForWidth, indexOf, invalidate, isEmpty, isEnabled, itemAt, layout, maximumSize, menuBar, minimumHeightForWidth, minimumSize, parentWidget, removeItem, removeWidget, setAlignment, setAlignment, setAlignment, setAlignment, setAlignment, setContentsMargins, setContentsMargins, setEnabled, setGeometry, setMargin, setMenuBar, setSizeConstraint, setWidgetSpacing, sizeConstraint, sizeHint, spacerItem, takeAt, update, widget, widgetSpacing

Methods inherited from class com.trolltech.qt.core.QObject

childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, event, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, indexOfProperty, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, properties, property, removeEventFilter, setObjectName, setParent, setProperty, startTimer, timerEvent, toString, userProperty

Methods inherited from class com.trolltech.qt.QtJambiObject

dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr

Methods inherited from class com.trolltech.qt.QSignalEmitter

blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread

Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal

__qt_signalInitialization

Methods inherited from class java.lang.Object

clone, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.trolltech.qt.QtJambiInterface

disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership

Constructor Detail

QFormLayout

public QFormLayout()

Constructs a new form layout with the given parent widget.

See also:

QWidget::setLayout().

QFormLayout

public QFormLayout(QWidget parent)

Constructs a new form layout with the given parent widget.

See also:

QWidget::setLayout().

Method Detail

addRow

public final void addRow(QLayout layout)

This is an overloaded member function, provided for convenience.

Adds the specified layout at the end of this form layout. The layout spans both columns.

addRow

public final void 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().

addRow

public final void addRow(QWidget widget)

This is an overloaded member function, provided for convenience.

Adds the specified widget at the end of this form layout. The widget spans both columns.

addRow

public final void addRow(java.lang.String labelText,
                         QLayout field)

This is an overloaded member function, provided for convenience.

This overload automatically creates a QLabel behind the scenes with labelText as its text.

addRow

public final void addRow(java.lang.String labelText,
                         QWidget field)

This is an overloaded member function, provided for convenience.

This overload automatically creates a QLabel behind the scenes with labelText as its text. The field is set as the new QLabel's buddy.

fieldGrowthPolicy

public final QFormLayout.FieldGrowthPolicy fieldGrowthPolicy()

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

See also:

formAlignment, and rowWrapPolicy.

formAlignment

public final Qt.Alignment formAlignment()

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. For QMacStyle, the default is Qt::AlignHCenter | Qt::AlignTop ; for the other styles, the default is Qt::AlignLeft | Qt::AlignTop .

See also:

labelAlignment, and rowWrapPolicy.

horizontalSpacing

public final int horizontalSpacing()

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.

See also:

verticalSpacing, QStyle::pixelMetric(), and PM_LayoutHorizontalSpacing .

insertRow

public final void insertRow(int row,
                            QLayout layout)

This is an overloaded member function, provided for convenience.

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.

insertRow

public final void insertRow(int row,
                            QWidget label,
                            QLayout 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().

insertRow

public final 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. If row is out of bounds, the new row is added at the end.

See also:

addRow().

insertRow

public final void insertRow(int row,
                            QWidget widget)

This is an overloaded member function, provided for convenience.

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.

insertRow

public final void insertRow(int row,
                            java.lang.String labelText,
                            QLayout field)

This is an overloaded member function, provided for convenience.

This overload automatically creates a QLabel behind the scenes with labelText as its text.

insertRow

public final void insertRow(int row,
                            java.lang.String labelText,
                            QWidget field)

This is an overloaded member function, provided for convenience.

This overload automatically creates a QLabel behind the scenes with labelText as its text. The field is set as the new QLabel's buddy.

itemAt

public final QLayoutItemInterface itemAt(int row,
                                         QFormLayout.ItemRole role)

Returns the layout item in the given row with the specified role (column). Returns 0 if there is no such item.

See also:

QLayout::itemAt(), and setItem().

labelAlignment

public final Qt.Alignment labelAlignment()

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

labelForField

public final QWidget labelForField(QLayout field)

This is an overloaded member function, provided for convenience.

labelForField

public final QWidget labelForField(QWidget field)

Returns the label associated with the given field.

See also:

itemAt().

rowCount

public final int rowCount()

Returns the number of rows in the form.

See also:

QLayout::count().

rowWrapPolicy

public final QFormLayout.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, 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.

setFieldGrowthPolicy

public final void setFieldGrowthPolicy(QFormLayout.FieldGrowthPolicy policy)

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

See also:

formAlignment, and rowWrapPolicy.

setFormAlignment

public final void setFormAlignment(Qt.AlignmentFlag[] alignment)

setFormAlignment

public final void setFormAlignment(Qt.Alignment 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. For QMacStyle, the default is Qt::AlignHCenter | Qt::AlignTop ; for the other styles, the default is Qt::AlignLeft | Qt::AlignTop .

See also:

labelAlignment, and rowWrapPolicy.

setHorizontalSpacing

public final void setHorizontalSpacing(int spacing)

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.

See also:

verticalSpacing, QStyle::pixelMetric(), and PM_LayoutHorizontalSpacing .

setLabelAlignment

public final void setLabelAlignment(Qt.AlignmentFlag[] alignment)

setLabelAlignment

public final void setLabelAlignment(Qt.Alignment alignment)

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

setLayout

public final void setLayout(int row,
                            QFormLayout.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().

setRowWrapPolicy

public final void setRowWrapPolicy(QFormLayout.RowWrapPolicy policy)

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, 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.

setSpacing

public final void setSpacing(int arg__1)

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

See also:

spacing(), setVerticalSpacing(), and setHorizontalSpacing().

setVerticalSpacing

public final void setVerticalSpacing(int spacing)

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.

See also:

horizontalSpacing, QStyle::pixelMetric(), and PM_LayoutHorizontalSpacing .

setWidget

public final void setWidget(int row,
                            QFormLayout.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().

spacing

public final int spacing()

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

See also:

setSpacing(), verticalSpacing(), and horizontalSpacing().

verticalSpacing

public final int verticalSpacing()

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.

See also:

horizontalSpacing, QStyle::pixelMetric(), and PM_LayoutHorizontalSpacing .

getItemPosition

public final QPair getItemPosition(int index)

Retrieves the row and role (column) of the item at the specified index. If index is out of bounds, -1 is returned in place of the row.

Parameters:

index - The index of the item for which to retrieve the position.

Returns:

A pair of an int (row of item) and an ItemRole (role of the item.)

getLayoutPosition

public final QPair getLayoutPosition(QLayout layout)

Retrieves the row and role (column) of the specified child layout. If the layout is not in the form layout, -1 is returned in place of the row.

Parameters:

layout - The layout for which to retrieve the position.

Returns:

A pair of an int (row of item) and an ItemRole (role of the item.)

getWidgetPosition

public final QPair getWidgetPosition(QWidget widget)

Retrieves the row and role (column) of the specified widget in the layout. If the widget is not in the form layout, -1 is returned in place of the row.

Parameters:

widget - The widget for which to retrieve the position.

Returns:

A pair of an int (row of item) and an ItemRole (role of the item.)

setItem

public final void setItem(int row,
                          QFormLayout.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 a IllegalArgumentException is thrown.