Qt Reference Documentation

- Qt 4.8
- ALL VERSIONS

- A
- A
- A
- Print

# Widgets and Layouts

## Widgets

Widgets are the primary elements for creating user interfaces in Qt. Widgets can display data and status information, receive user input, and provide a container for other widgets that should be grouped together. A widget that is not embedded in a parent widget is called a window.

The QWidget class provides the basic capability to render to the screen, and to handle user input events. All UI elements that Qt provides are either subclasses of QWidget, or are used in connection with a QWidget subclass. Creating custom widgets is done by subclassing QWidget or a suitable subclass and reimplementing the virtual event handlers.

## Layouts

Layouts are an elegant and flexible way to automatically arrange child widgets within their container. Each widget reports its size requirements to the layout through the sizeHint and sizePolicy properties, and the layout distributes the available space accordingly.

Qt Designer is a powerful tool for interactively creating and arranging widgets in layouts.

## Widget Styles

Styles draw on behalf of widgets and encapsulate the look and feel of a GUI. Qt's built-in widgets use the QStyle class to perform nearly all of their drawing, ensuring that they look exactly like the equivalent native widgets.

Qt Style Sheets are a powerful mechanism that allows you to customize the appearance of widgets, in addition to what is already possible by subclassing QStyle.

## The Widget Classes

The following sections list the widget classes. See the Qt Widget Gallery for some examples.

### Basic Widgets

These basic widgets (controls), e.g. buttons, comboboxes and scroll bars, are designed for direct use.

QCheckBox | Checkbox with a text label
QComboBox | Combined button and popup list
QCommandLinkButton | Vista style command link button
QDateEdit | Widget for editing dates based on the QDateTimeEdit widget
QDateTimeEdit | Widget for editing dates and times
QDial | Rounded range control (like a speedometer or potentiometer)
QDoubleSpinBox | Spin box widget that takes doubles
QFocusFrame | Focus frame which can be outside of a widget's normal paintable area
QFontComboBox | Combobox that lets the user select a font family
QLCDNumber | Displays a number with LCD-like digits
QLabel | Text or image display
QLineEdit | One-line text editor
QMenu | Menu widget for use in menu bars, context menus, and other popup menus
QProgressBar | Horizontal or vertical progress bar
QPushButton | Command button
QRadioButton | Radio button with a text label
QScrollArea | Scrolling view onto another widget
QScrollBar | Vertical or horizontal scroll bar
QSizeGrip | Resize handle for resizing top-level windows
QSlider | Vertical or horizontal slider
QSpinBox | Spin box widget
QTabBar | Tab bar, e.g. for use in tabbed dialogs
QTabWidget | Stack of tabbed widgets
QTimeEdit | Widget for editing times based on the QDateTimeEdit widget
QToolBox | Column of tabbed widget items
QToolButton | Quick-access button to commands or options, usually used inside a QToolBar
QWidget | The base class of all user interface objects

### Advanced Widgets

Advanced GUI widgets, e.g. tab widgets and progress bars, provide more complex user interface controls.

QCalendarWidget | Monthly based calendar widget allowing the user to select a date
QColumnView | Model/view implementation of a column view
QDataWidgetMapper | Mapping between a section of a data model to widgets
QDesktopWidget | Access to screen information on multi-head systems
QListView | List or icon view onto a model
QMacCocoaViewContainer | Widget for Mac OS X that can be used to wrap arbitrary Cocoa views (i.e., NSView subclasses) and insert them into Qt hierarchies
QMacNativeWidget | Widget for Mac OS X that provides a way to put Qt widgets into Carbon or Cocoa hierarchies depending on how Qt was configured
QTableView | Default model/view implementation of a table view
QTreeView | Default model/view implementation of a tree view
QUndoView | Displays the contents of a QUndoStack
QWSEmbedWidget | Enables embedded top-level widgets in Qt for Embedded Linux
QWebView | Widget that is used to view and edit web documents
QX11EmbedContainer | XEmbed container widget
QX11EmbedWidget | XEmbed client widget
Phonon::VideoWidget | Widget that is used to display video

### Organizer Widgets

Classes like splitters, tab bars, button groups, etc are used for organizing and grouping GUI primitives into more complex applications and dialogs.

QButtonGroup | Container to organize groups of button widgets
QGroupBox | Group box frame with a title
QSplitter | Implements a splitter widget
QSplitterHandle | Handle functionality of the splitter
QStackedWidget | Stack of widgets where only one widget is visible at a time
QTabWidget | Stack of tabbed widgets

### Abstract Widget Classes

The abstract widget classes are base classes. They are not usable as standalone classes but provide functionality when they are subclassed.

QAbstractButton | The abstract base class of button widgets, providing functionality common to buttons
QAbstractScrollArea | Scrolling area with on-demand scroll bars
QAbstractSlider | Integer value within a range
QAbstractSpinBox | Spinbox and a line edit to display values
QDialog | The base class of dialog windows
QFrame | The base class of widgets that can have a frame