com.trolltech.qt.gui
Class QFormLayout

java.lang.Object
  extended by com.trolltech.qt.internal.QSignalEmitterInternal
      extended by com.trolltech.qt.QSignalEmitter
          extended by com.trolltech.qt.QtJambiObject
              extended by com.trolltech.qt.core.QObject
                  extended by com.trolltech.qt.gui.QLayout
                      extended by 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:

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.