Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.trolltech.qt.gui
Class QFormLayout

    java.lang.Object
      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("&Name:"));
              emailLabel->setBuddy(emailLineEdit);

              ageLabel = new QLabel(tr("&Name:"));
              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` | Qtopia 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 Qtopia 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->setFormStyle(QFormLayout::MacStyle);
            formLayout->setLabelAlignment(Qt::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.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9`

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)` Adds the specified `layout` at the end of this form layout.
`void` | `addRow(QWidget widget)` Adds the specified `widget` at the end of this form layout.
`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 overload automatically creates a `QLabel` behind the scenes with `labelText` as its text.
`void` | `addRow(java.lang.String labelText, QWidget field)` This overload automatically creates a `QLabel` behind the scenes with `labelText` as its text.
`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.
`static QFormLayout` | `fromNativePointer(QNativePointer nativePointer)` This method returns the QFormLayout instance pointed to by `nativePointer`.
`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)` Inserts the specified `layout` at position `row` in this form layout.
`void` | `insertRow(int row, QWidget widget)` Inserts the specified `widget` at position `row` in this form layout.
`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 overload automatically creates a `QLabel` behind the scenes with `labelText` as its text.
`void` | `insertRow(int row, java.lang.String labelText, QWidget field)` This overload automatically creates a `QLabel` behind the scenes with `labelText` as its text.
`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)`
`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)` This property holds the alignment of the form layout's contents within the layout's geometry.
`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)` This property holds the horizontal alignment of the labels.
`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 on top of each other.
`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 on top of each other.

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 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)

  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)

  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 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 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 Qtopia 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. 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)

  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)

  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 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 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)

### 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 Qtopia 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 Qtopia 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)

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

### 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. 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)

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

### 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 Qtopia 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 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()`, 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 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()`, and `PM_LayoutHorizontalSpacing` .

### fromNativePointer

    public static QFormLayout fromNativePointer(QNativePointer nativePointer)

  This method returns the QFormLayout instance pointed to by `nativePointer`.

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD