QDockWidget Class
The QDockWidget class provides a widget that can be docked inside a QMainWindow or floated as a top-level window on the desktop. More...
| Header: | #include <QDockWidget> |
| qmake: | QT += widgets |
| Inherits: | QWidget |
Public Types
| enum | DockWidgetFeature { DockWidgetClosable, DockWidgetMovable, DockWidgetFloatable, DockWidgetVerticalTitleBar, AllDockWidgetFeatures, NoDockWidgetFeatures } |
Properties
- allowedAreas : Qt::DockWidgetAreas
- features : DockWidgetFeatures
- floating : bool
- windowTitle : QString
Public Functions
| Qt::DockWidgetAreas | allowedAreas() const |
| QDockWidget::DockWidgetFeatures | features() const |
| bool | isFloating() const |
| void | setAllowedAreas(Qt::DockWidgetAreas areas) |
| void | setFeatures(QDockWidget::DockWidgetFeatures features) |
| void | setFloating(bool floating) |
Signals
| void | allowedAreasChanged(Qt::DockWidgetAreas allowedAreas) |
| void | featuresChanged(QDockWidget::DockWidgetFeatures features) |
Detailed Description
QDockWidget provides the concept of dock widgets, also know as tool palettes or utility windows. Dock windows are secondary windows placed in the dock widget area around the central widget in a QMainWindow.
Dock windows can be moved inside their current area, moved into new areas and floated (e.g., undocked) by the end-user. The QDockWidget API allows the programmer to restrict the dock widgets ability to move, float and close, as well as the areas in which they can be placed.
Appearance
A QDockWidget consists of a title bar and the content area. The title bar displays the dock widgets window title, a float button and a close button. Depending on the state of the QDockWidget, the float and close buttons may be either disabled or not shown at all.
The visual appearance of the title bar and buttons is dependent on the style in use.
A QDockWidget acts as a wrapper for its child widget, set with setWidget(). Custom size hints, minimum and maximum sizes and size policies should be implemented in the child widget. QDockWidget will respect them, adjusting its own constraints to include the frame and title. Size constraints should not be set on the QDockWidget itself, because they change depending on whether it is docked; a docked QDockWidget has no frame and a smaller title bar.
Note: On macOS, if the QDockWidget has a native window handle (for example, if winId() is called on it or the child widget), then due to a limitation it will not be possible to drag the dock widget when undocking. Starting the drag will undock the dock widget, but a second drag will be needed to move the dock widget itself.
See also QMainWindow and Dock Widgets Example.
Member Type Documentation
enum QDockWidget::DockWidgetFeature
| Constant | Value | Description |
|---|---|---|
QDockWidget::DockWidgetClosable | 0x01 | The dock widget can be closed. On some systems the dock widget always has a close button when it's floating (for example on MacOS 10.5). |
QDockWidget::DockWidgetMovable | 0x02 | The dock widget can be moved between docks by the user. |
QDockWidget::DockWidgetFloatable | 0x04 | The dock widget can be detached from the main window, and floated as an independent window. |
QDockWidget::DockWidgetVerticalTitleBar | 0x08 | The dock widget displays a vertical title bar on its left side. This can be used to increase the amount of vertical space in a QMainWindow. |
QDockWidget::AllDockWidgetFeatures | DockWidgetClosable|DockWidgetMovable|DockWidgetFloatable | (Deprecated) The dock widget can be closed, moved, and floated. Since new features might be added in future releases, the look and behavior of dock widgets might change if you use this flag. Please specify individual flags instead. |
QDockWidget::NoDockWidgetFeatures | 0x00 | The dock widget cannot be closed, moved, or floated. |
Property Documentation
allowedAreas : Qt::DockWidgetAreas
areas where the dock widget may be placed
The default is Qt::AllDockWidgetAreas.
Access functions:
| Qt::DockWidgetAreas | allowedAreas() const |
| void | setAllowedAreas(Qt::DockWidgetAreas areas) |
Notifier signal:
| void | allowedAreasChanged(Qt::DockWidgetAreas allowedAreas) |
See also Qt::DockWidgetArea.
features : DockWidgetFeatures
This property holds whether the dock widget is movable, closable, and floatable
By default, this property is set to a combination of DockWidgetClosable, DockWidgetMovable and DockWidgetFloatable.
Access functions:
| QDockWidget::DockWidgetFeatures | features() const |
| void | setFeatures(QDockWidget::DockWidgetFeatures features) |
Notifier signal:
| void | featuresChanged(QDockWidget::DockWidgetFeatures features) |
See also DockWidgetFeature.
floating : bool
This property holds whether the dock widget is floating
A floating dock widget is presented to the user as an independent window "on top" of its parent QMainWindow, instead of being docked in the QMainWindow.
By default, this property is true.
When this property changes, the topLevelChanged() signal is emitted.
Access functions:
| bool | isFloating() const |
| void | setFloating(bool floating) |
See also isWindow() and topLevelChanged().
windowTitle : QString
This property holds the dock widget title (caption)
By default, this property contains an empty string.
Access functions:
| QString | windowTitle() const |
| void | setWindowTitle(const QString &) |
Notifier signal:
| void | windowTitleChanged(const QString &title) |