The <widget> Element

| Chapter 9. The File Format Of .ui Files |

# The `<widget>` Element

As its name implies, the widget element describes one widget. At the top level of the `.ui` file, there must be exactly one such element for the top-level widget of the form, but this element can in turn contain other `<widget>` elements.

A `<widget>` element can have the following subelements:

`<class>`

  There must be exactly one such element that describes the C++ class of the widget (like `QWidget`).

`<property>`

  There can be any number of such elements that describe the properties of the widget that differ from the default. See the next section for a description of how `<property>` elements should look.

`<attribute>`

  There can be any number of such elements that describe the attributes of the widget. Attributes are like properties, but are not defined in the widget and need to be treated specially. This element has the same syntax as the `<property>` element.

`<item>`

  There can be any number of such elements that describe the items of this widget if the widget can contain items (like list boxes or icon views). See the section called The `<item>` Element for the exact syntax of this item.

`<column>`

  There can be any number of such elements that describe the columns of this widget if the widget is a list view. See the section called The `<column>` Element for the exact syntax of this item.

Child widgets

  Child widgets can be specified in one of four ways:

  Any number of `<widget>` elements

    If the widget does not use any layout management, then the children are directly specified as `<widget>` elements.

  One `<hbox>` element

    If the widget uses a horizontal box layout as its outermost layout, then exactly one `<hbox>` is specified, which in turn specifies the child widgets. See the section called The `<hbox>` Element for the exact syntax of this element.

  One `<vbox>` element

    If the widget uses a vertical box layout as its outermost layout, then exactly one `<vbox>` is specified, which in turn specifies the child widgets. See the section called The `<vbox>` Element for the exact syntax of this element.

  One `<grid>` element

    If the widget uses a grid layout as its outermost layout, then exactly one `<grid>` is specified, which in turn specifies the child widgets. See the section called The `<grid>` Element for the exact syntax of this element.

## The `<property>` Element

This element describes a property of a widget or a layout. Each property has as its first child a `<name>` element that describes the name of the property (like `geometry`) and as its second child an element whose name describes the type and whose contents describe the value of the property. Table 9-1 lists the possible type names together with a description of their values.

Table 9-1. Property Types

Element Name | Type | Description of the Value | Example
--- | --- | --- | ---
string | Any Unicode string value (saved in UTF-8) | String | <string>Some Text</string>
cstring | Any c-string (8-bit) value | CString | <string>Some Text</string>
bool | Any boolean value | Bool (1|0) | <bool>1</bool>
number | Any signed numerical value | Integer | <number>-4</number>
number | Any unsigned numerical value | Unsigned integer | <number>1</number>
enum | Enum key | String | <enum>StrongFocus</enum>
set | Set (OR'd integers) | StringList joined with '|' | <set>AlignLeft|AlignTop|WordWrap</set>
rect | Rectangles | <x>Integer</x> <y>Integer</y> <width>Integer</width> <height>Integer</height> If you leave out one of the elements, the value of it defaults to zero (0). | <rect> <x>20</x> <y>30</y> <width>200</width> <height>25</height> </rect>
point | Points (coordinates) | <x>Integer</x> <y>Integer</y> If you leave out one of the elements, the value of it defaults to zero (0). | <point> <x>20</x> <y>30</y> </point>
size | Sizes | <width>Integer</width> <height>Integer</height> If you leave out one of the elements, the value of it defaults to zero (0). | <size> <width>200</width> <height>25</height> </size>
font | Font description | <family>String</family> <pointsize>Integer</pointsize> <weight>Integer</weight> <italic>Boolean</italic> <underline>Boolean</underline> <strikeout>Boolean</strikeout> | <font> <family>Times</family> <pointsize>12</pointsize> <weight>50</weight> <italic>1</italic> <underline>0</underline> <strikeout>0</strikeout> </font>
color | Color description | <red>Integer</red> <green>Integer</green> <blue>Integer</blue> | <color> <red>192</red> <green>200</green> <blue>50</blue> </color>
pixmap/image/imageset | Pixmap | Depending on whether images are saved inline or not (see earlier in the "Header Elements" section), this element looks different: Inline <pixmap><key of pixmap in the pixmap collection></pixmap> The same is used for saving images and iconsets at the moment; just replace 'pixmap' with 'image' or 'iconset.' There is no special support for icon sets yet. Not Inline (Function) <pixmap><Arguments for pixmap-loading function></pixmap> The same is used for saving images and iconsets at the moment; just replace 'pixmap' with 'image' or 'iconset.' There is no special support for icon sets. | <pixmap>image1</pixmap>
sizepolicy | SizePolicy (saved as int) | <hsizetype>SizeType</hsizetype> <vsizetype>SizeType</vsizetype> SizeType is saved as int and can be one of the following: Fixed (0) Minimum (1) Maximum (4) Preferred (5) MinimumExpanding (3) Expanding (7) | <hsizetype>1</hsizetype> <vsizetype>3</vsizetype>
palette | Palette | <palette> <active> <color> rgb of Foreground </color> <color> rgb of Button </color> <color> rgb of Light </color> <color> rgb of Midlight </color> <color> rgb of Dark </color> <color> rgb of Mid </color> <color> rgb of Text </color> <color> rgb of BrightText </color> <color> rgb of ButtonText </color> <color> rgb of Base </color> <color> rgb of Background </color> <color> rgb of Shadow </color> <color> rgb of Highlight </color> <color> rgb of HighlightText </color> </active> <disabled> ColorGroup of disabled palette </disabled> <inactive> ColorGroup of inactive palette </inactive> </palette> | <palette> <active> <color> <red>0</red> <green>0</green> <blue>0</blue> </color> <color> <red>170</red> <green>170</green> <blue>255</blue> </color> <color> <red>255</red> <green>255</green> <blue>255</blue> </color> <color> <red>212</red> <green>212</green> <blue>255</blue> </color> <color> <red>85</red> <green>85</green> <blue>127</blue> </color> <color> <red>113</red> <green>113</green> <blue>170</blue> </color> <color> <red>0</red> <green>0</green> <blue>0</blue> </color> <color> <red>255</red> <green>255</green> <blue>255</blue> </color> <color> <red>0</red> <green>0</green> <blue>0</blue> </color> <color> <red>255</red> <green>255</green> <blue>255</blue> </color> <color> <red>218</red> <green>218</green> <blue>218</blue> </color> <color> <red>0</red> <green>0</green> <blue>0</blue> </color> <color> <red>90</red> <green>36</green> <blue>0</blue> </color> <color> <red>255</red> <green>255</green> <blue>255</blue> </color> </active> <disabled> ...... </disabled> <inactive> ...... </inactive> </palette>
cursor | Cursor saved as int |
<cursor>cursor</cursor>
The following int values are defined for cursor: ArrowCursor (0) UpArrowCursor (1) CrossCursor (2) WaitCursor (3) IbeamCursor (4) SizeVerCursor (5) SizeHorCursor (6) SizeBDiagCursor (7) SizeFDiagCursor (8) SizeAllCursor (9) BlankCursor (10) SplitVCursor (11) SplitHCursor (12) PointingHandCursor (13) ForbiddenCursor (14) | <cursor>5</cursor>

## The `<hbox>` Element

This element describes a layout that arranges its children from left to right. It must be a child of a `<widget>` element. This widget is then normally a container widget (e.g., a `QGroupBox`) or a temporary `QLayoutWidget`. The following child elements are defined:

`<property>`

  There can be any number of these elements, which describe a property of the layout.

`<widget>`

  There can be any number of these elements, which describe a child widget that is managed by the layout.

`<spacer>`

  There can be any number of these elements, which describe a spacer in the layout (see the section called The `<spacer>` Element ).

## The `<vbox>` Element

This element describes a layout that arranges its children from top to bottom. It must be a child of a `<widget>` element. This widget is then normally a container widget (e.g., a `QGroupBox`) or a temporary `QLayoutWidget`. The following child elements are defined:

`<property>`

  There can be any number of these elements, which describe a property of the layout.

`<widget>`

  There can be any number of these elements, which describe a child widget that is managed by the layout.

`<spacer>`

  There can be any number of these elements, which describe a spacer in the layout (see the section called The `<spacer>` Element ).

## The `<grid>` Element

This element describes a layout that arranges its children in a grid. It must be a child of a `<widget>` element. This widget is then normally a container widget (e.g., a `QGroupBox`) or a temporary `QLayoutWidget`. The following child elements are defined:

`<property>`

  There can be any number of these elements, which describe a property of the layout.

`<widget>`

  There can be any number of these elements, which describe a child widget that is managed by the layout.

  Besides the elements ordinarily defined as subelements of `<widget>`, there can be `<row>` and `<col>` elements, which specify the position of the widget in the grid. These elements themselves can have one or both of the attributes `rowspan` and `colspan`, which specify the number of rows and columns the cell should cover. The default is 1.

`<spacer>`

  There can be any number of these elements, which describe a spacer in the layout (see the next section).

  Besides the elements ordinarily defined as subelements of `<spacer>`, there can be `<row>` and `<col>` elements, which specify the position of the widget in the grid. These elements themselves can have one or both of the attributes `rowspan` and `colspan`, which specify the number of rows and columns the cell should cover. The default is 1.

## The `<spacer>` Element

This element describes a spacer item inside a layout. It has four properties:

`name`

  This property, of the type string, describes the name of the item.

`orientation`

  This property, of the type enum with the valid values `Horizontal` and `Vertical`, describes the orientation of the item.

`sizeType`

  This property, of the type enum, describes how the item expands in its direction. See the Qt Reference Documentation for size policies for more information.

`geometry`

  This property, of the type rect, describes the geometry of the spacer, which is normally useful only for fixed spacing.

## The `<item>` Element

This element describes an item of a widget if this widget can contain items (like list boxes, icon views, etc.). The item element contains exactly one child element that describes the item. This child element is a `<property>` element. Valid property names are `text` and `pixmap`, depending on where to insert the item.

As list views can hold a tree of items, the `<item>` element can contain other `<item>` elements, which are then child items. Also, as list views can have many columns, an `<item>` element contains a `text` and a `pixmap` property for each column. The columns of a list view are described with a `<column>` element (see the next section).

## The `<column>` Element

This element describes the columns of a list view widget. A list view can contain multiple column elements. A column element contains the following properties, which are all optional:

`text`

  This property, of type string, contains the column label.

`pixmap`

  This property, of type pixmap, contains the column pixmap.

`resizable`

  This property, of type bool, describes whether the column may be resized by the user.

`movable`

  This property, of type bool, describes whether the column may be moved by the user.

The File Format Of .ui Files |  | The Pixmaps In The `<images>` Element