|  | Home · Overviews · Examples

# QWidget Class Reference
[com.trolltech.qt.gui module]

The `QWidget` class is the base class of all user interface objects. More...

Inherits `QObject` and `QObject`.

Inherited by `QAbstractButton`, `QAbstractSlider`, `QAbstractSpinBox`, `QCalendarWidget`, `QComboBox`, `QDesignerResourceBrowserInterface`, `QDesktopWidget`, `QDialog`, `QDialogButtonBox`, `QDockWidget`, `QFocusFrame`, `QFrame`, `QGLWidget`, `QGroupBox`, `QLineEdit`, `QMainWindow`, `QMdiSubWindow`, `QMenu`, `QMenuBar`, `QProgressBar`, `QRubberBand`, `QSizeGrip`, `QSplashScreen`, `QSplitterHandle`, `QStatusBar`, `QSvgWidget`, `QTabBar`, `QTabWidget`, `QToolBar`, `QWizardPage`, and `QWorkspace`.

## Detailed Description

The `QWidget` class is the base class of all user interface objects.

The widget is the atom of the user interface: it receives mouse, keyboard and other events from the window system, and paints a representation of itself on the screen. Every widget is rectangular, and they are sorted in a Z-order. A widget is clipped by its parent and by the widgets in front of it.

A widget that isn't embedded in a parent widget is called a window. Usually, windows have a frame and a title bar, although it is also possible to create windows without such decoration using suitable window flags). In Qt, `QMainWindow` and the various subclasses of `QDialog` are the most common window types.

Every widget's constructor accepts one or two standard arguments:

1. `QWidget *parent = 0` is the parent of the new widget. If it is 0 (the default), the new widget will be a window. If not, it will be a child of parent, and be constrained by parent's geometry (unless you specify Qt::Window as window flag).
2. `Qt::WindowFlags f = 0` (where available) sets the window flags; the default is suitable for almost all widgets, but to get, for example, a window without a window system frame, you must use special flags.

`QWidget` has many member functions, but some of them have little direct functionality; for example, `QWidget` has a font property, but never uses this itself. There are many subclasses which provide real functionality, such as `QLabel`, `QPushButton`, `QListWidget`, and `QTabWidget`.

### Top-Level and Child Widgets

A widget without a parent widget is always an independent window (top-level widget). For these widgets, `setWindowTitle` and `setWindowIcon` set the title bar and icon respectively.

Non-window widgets are child widgets, and are displayed within their parent widgets. Most widgets in Qt are mainly useful as child widgets. For example, it is possible to display a button as a top-level window, but most people prefer to put their buttons inside other widgets, such as `QDialog`.

The above diagram shows a `QGroupBox` widget being used to hold various child widgets in a layout provided by `QGridLayout`. The `QLabel` child widgets have been outlined to indicate their full sizes.

If you want to use a `QWidget` to hold child widgets you will usually want to add a layout to the parent `QWidget`. See Layout Classes for more information about these.

### Composite Widgets

When a widgets is used as a container to group a number of child widgets, it is known as a composite widget. These can be created by constructing a widget with the required visual properties - a `QFrame`, for example - and adding child widgets to it, usually managed by a layout. The above diagram shows such a composite widget that was created using Qt Designer.

Composite widgets can also be created by subclassing a standard widget, such as `QWidget` or `QFrame`, and adding the necessary layout and child widgets in the constructor of the subclass. Many of the examples provided with Qt use this approach, and it is also covered in the Qt Tutorial.

### Custom Widgets and Painting

Since `QWidget` is a subclass of `QPaintDevice`, subclasses can be used to display custom content that is composed using a series of painting operations with an instance of the `QPainter` class. This approach contrasts with the canvas-style approach used by the Graphics View Framework where items are added to a scene by the application and are rendered by the framework itself.

Each widget performs all painting operations from within its `paintEvent` function. This is called whenever the widget needs to be redrawn, either as a result of some external change or when requested by the application.

The Analog Clock example shows how a simple widget can handle paint events.

### Size Hints and Size Policies

When implementing a new widget, it is almost always useful to reimplement `sizeHint` to provide a reasonable default size for the widget and to set the correct size policy with `setSizePolicy`.

By default, composite widgets which do not provide a size hint will be sized according to the space requirements of their child widgets.

The size policy lets you supply good default behavior for the layout management system, so that other widgets can contain and manage yours easily. The default size policy indicates that the size hint represents the preferred size of the widget, and this is often good enough for many widgets.

### Events

Widgets respond to events that are typically caused by user actions. Qt delivers events to widgets by calling specific event handler functions with instances of `QEvent` subclasses containing information about each event.

If your widget only contains child widgets, you probably do not need to implement any event handlers. If you want to detect a mouse click in a child widget call the child's `underMouse` function inside the widget's `mousePressEvent`.

The Scribble example implements a wider set of events to handle mouse movement, button presses, and window resizing.

You will need to supply the behavior and content for your own widgets, but here is a brief overview of the events that are relevant to `QWidget`, starting with the most common ones:

- `paintEvent` is called whenever the widget needs to be repainted. Every widget which displays custom content must implement it. Painting using a `QPainter` can only take place in a `paintEvent` or a function called by a `paintEvent`.
- `resizeEvent` is called when the widget has been resized.
- `mousePressEvent` is called when a mouse button is pressed when the mouse is inside it, or when it has grabbed the mouse using `grabMouse`.
- `mouseReleaseEvent` is called when a mouse button is released. A widget receives mouse release events when it has received the corresponding mouse press event. This means that if the user presses the mouse inside your widget, then drags the mouse to somewhere else before releasing the mouse button, your widget receives the release event. There is one exception: if a popup menu appears while the mouse button is held down, this popup immediately steals the mouse events.
- `mouseDoubleClickEvent` is called when the user double clicks in the widget. If the user double-clicks, the widget receives a mouse press event, a mouse release event and finally this event instead of a second mouse press event. (Some mouse move events may also be received if the user doesn't hold the mouse steady during this operation.) It is not possible to distinguish a click from a double click until the second click arrives. (This is one reason why most GUI books recommend that double clicks be an extension of single clicks, rather than trigger a different action.)

Widgets that accept keyboard input need to reimplement a few more event handlers:

- `keyPressEvent` is called whenever a key is pressed, and again when a key has been held down long enough for it to auto-repeat. Note that the Tab and Shift+Tab keys are only passed to the widget if they are not used by the focus-change mechanisms. To force those keys to be processed by your widget, you must reimplement QWidget::event().
- `focusInEvent` is called when the widget gains keyboard focus (assuming you have called `setFocusPolicy`). Well written widgets indicate that they own the keyboard focus in a clear but discreet way.
- `focusOutEvent` is called when the widget loses keyboard focus.

Some widgets will also need to reimplement some of the less common event handlers:

- `mouseMoveEvent` is called whenever the mouse moves while a button is held down. This can be useful during drag and drop operations. If you call `setMouseTracking`(true), you get mouse move events even when no buttons are held down. (See also the guide to Drag and Drop.)
- `keyReleaseEvent` is called whenever a key is released, and also while it is held down if the key is auto-repeating. In that case the widget receives a pair of key release and key press events for every repeat. Note that the Tab and Shift+Tab keys are only passed to the widget if they are not used by the focus-change mechanisms. To force those keys to be processed by your widget, you must reimplement QWidget::event().
- `wheelEvent` is called whenever the user turns the mouse wheel while the widget has the focus.
- `enterEvent` is called when the mouse enters the widget's screen space. (This excludes screen space owned by any children of the widget.)
- `leaveEvent` is called when the mouse leaves the widget's screen space. Note that if the mouse enters a child widget it will not cause a `leaveEvent`.
- `moveEvent` is called when the widget has been moved relative to its parent.
- `closeEvent` is called when the user closes the widget (or when `close` is called).

There are also some rather obscure events described in the QEvent::Type documentation. You need to reimplement `event` directly to handle these. The default implementation of `event` handles Tab and Shift+Tab (to move the keyboard focus), and passes on most other events to one of the more specialized handlers above.

Events and the mechanism used to deliver them are covered in the Events and Event Filters document.

### Groups of Functions and Properties

Context | Functions and Properties
--- | ---
Window functions | `show`, `hide`, `raise`, `lower`, `close`.
Top-level windows | `windowModified`, `windowTitle`, `windowIcon`, `windowIconText`, `isActiveWindow`, `activateWindow`, minimized, `showMinimized`, maximized, `showMaximized`, `fullScreen`, `showFullScreen`, `showNormal`.
Window contents | `update`, `repaint`, `scroll`.
Geometry | pos, `x`, `y`, rect, size, `width`, `height`, `move`, `resize`, `sizePolicy`, `sizeHint`, `minimumSizeHint`, `updateGeometry`, `layout`, `frameGeometry`, geometry, `childrenRect`, `childrenRegion`, `adjustSize`, `mapFromGlobal`, `mapToGlobal`, `mapFromParent`, `mapToParent`, `maximumSize`, `minimumSize`, `sizeIncrement`, `baseSize`, `setFixedSize`
Mode | visible, `isVisibleTo`, enabled, `isEnabledTo`, modal, `isWindow`, `mouseTracking`, `updatesEnabled`, `visibleRegion`.
Look and feel | `style`, `setStyle`, `styleSheet`, cursor, font, palette, `backgroundRole`, `setBackgroundRole`, `fontInfo`, `fontMetrics`.
Keyboard focus functions | focus, `focusPolicy`, `setFocus`, `clearFocus`, `setTabOrder`, `setFocusProxy`, `focusNextChild`, `focusPreviousChild`.
Mouse and keyboard grabbing | `grabMouse`, `releaseMouse`, `grabKeyboard`, `releaseKeyboard`, `mouseGrabber`, `keyboardGrabber`.
Event handlers | `event`, `mousePressEvent`, `mouseReleaseEvent`, `mouseDoubleClickEvent`, `mouseMoveEvent`, `keyPressEvent`, `keyReleaseEvent`, `focusInEvent`, `focusOutEvent`, `wheelEvent`, `enterEvent`, `leaveEvent`, `paintEvent`, `moveEvent`, `resizeEvent`, `closeEvent`, `dragEnterEvent`, `dragMoveEvent`, `dragLeaveEvent`, `dropEvent`, `childEvent`, `showEvent`, `hideEvent`, `customEvent`. `changeEvent`,
System functions | `parentWidget`, `window`, `setParent`, `winId`, find(), `metric`.
Interactive help | `setToolTip`, `setWhatsThis`

### Widget Style Sheets

In addition to the standard widget styles for each platform, widgets can also be styled according to rules specified in a style sheet. This feature enables you to customize the appearance of specific widgets to provide visual cues to users about their purpose; for example, a button could be styled in a particular way to indicate that it performs a destructive action.

The use of widgets style sheets is described in more detail in Qt Style Sheets.

### Transparency and Double Buffering

From Qt 4.0, `QWidget` automatically double-buffers its painting, so there's no need to write double-buffering code in `paintEvent` to avoid flicker. Additionally, it became possible for widgets to propagate their contents to children, in order to enable transparency effects, by setting the Qt::WA_ContentsPropagated widget attribute - this is now deprecated in Qt 4.1.

In Qt 4.1, the contents of parent widgets are propagated by default to each of their children. Custom widgets can be written to take advantage of this feature by only updating irregular regions (to create non-rectangular child widgets), or by using painting with colors that have less than the full alpha component. The following diagram shows how attributes and properties of a custom widget can be fine-tuned to achieve different effects.

In the above diagram, a semi-transparent rectangular child widget with an area removed is constructed and added to a parent widget (a `QLabel` showing a pixmap) then different properties and widget attributes are set to achieve different effects:

- The left widget has no additional properties or widget attributes set. This default state suits most custom widgets that use transparency or are irregularly-shaped, and that do not paint over their entire area with an opaque brush.
- The center widget has the `autoFillBackground` property set. This property is used with custom widgets that rely on the widget to supply a default background, and do not paint over their entire area with an opaque brush.
- The right widget has the Qt::WA_OpaquePaintEvent widget attribute set. This indicates that the widget will paint over its entire area with opaque colors. The widget's area will initially be uninitialized (represented in the diagram by a red diagonal grid pattern that shines through the overpainted area). This is useful for widgets that need to paint their own specialized contents quickly and that do not need a default filled background.

For rapidly updating custom widgets with simple background colors, such as real-time plotting or graphing widgets, it is better to define a suitable background color (using `setBackgroundRole` with the QPalette::Window role), set the `autoFillBackground` property, and only implement the necessary drawing functionality in the widget's `paintEvent`.

For rapidly updating custom widgets that constantly paint over their entire areas with opaque content, such as video streaming widgets, it is better to set the widget's Qt::WA_OpaquePaintEvent, avoiding any unnecessary overhead associated with repainting the widget's background.

If a widget has both the Qt::WA_OpaquePaintEvent widget attribute and the `autoFillBackground` property set, the Qt::WA_OpaquePaintEvent attribute takes precedence. You should choose just one of these depending on your requirements.

In Qt 4.1, the contents of parent widgets are also propagated to standard Qt widgets. This can lead to some unexpected results if the parent widget is decorated in a non-standard way, as shown in the diagram below.

The scope for customizing the painting behavior of standard Qt widgets, without resorting to subclassing, is slightly less than that possible for custom widgets. Usually, the desired appearance of a standard widget can be achieved by setting its `autoFillBackground` property.

See also `QEvent`, `QPainter`, `QGridLayout`, and `QBoxLayout`.