QDockWidget Class
La clase QDockWidget proporciona un widget que puede acoplarse dentro de un « QMainWindow » o mostrarse como ventana flotante de nivel superior en el escritorio. Más información...
| Encabezado: | #include <QDockWidget> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | QWidget |
Tipos públicos
| enum | DockWidgetFeature { DockWidgetClosable, DockWidgetMovable, DockWidgetFloatable, DockWidgetVerticalTitleBar, NoDockWidgetFeatures } |
| flags | DockWidgetFeatures |
Propiedades
|
|
Funciones públicas
| QDockWidget(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags()) | |
| QDockWidget(const QString &title, QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags()) | |
| virtual | ~QDockWidget() |
| Qt::DockWidgetAreas | allowedAreas() const |
| Qt::DockWidgetArea | dockLocation() const |
| QDockWidget::DockWidgetFeatures | features() const |
| bool | isAreaAllowed(Qt::DockWidgetArea area) const |
| bool | isFloating() const |
| void | setAllowedAreas(Qt::DockWidgetAreas areas) |
(since 6.9) void | setDockLocation(Qt::DockWidgetArea area) |
| void | setFeatures(QDockWidget::DockWidgetFeatures features) |
| void | setFloating(bool floating) |
| void | setTitleBarWidget(QWidget *widget) |
| void | setWidget(QWidget *widget) |
| QWidget * | titleBarWidget() const |
| QAction * | toggleViewAction() const |
| QWidget * | widget() const |
Señales
| void | allowedAreasChanged(Qt::DockWidgetAreas allowedAreas) |
| void | dockLocationChanged(Qt::DockWidgetArea area) |
| void | featuresChanged(QDockWidget::DockWidgetFeatures features) |
| void | topLevelChanged(bool topLevel) |
| void | visibilityChanged(bool visible) |
Funciones protegidas
| virtual void | initStyleOption(QStyleOptionDockWidget *option) const |
Funciones protegidas reimplementadas
| virtual void | changeEvent(QEvent *event) override |
| virtual void | closeEvent(QCloseEvent *event) override |
| virtual bool | event(QEvent *event) override |
| virtual void | paintEvent(QPaintEvent *event) override |
Descripción detallada
QDockWidget ofrece el concepto de widgets acoplables, también conocidos como paletas de herramientas o ventanas de utilidades. Las ventanas acoplables son ventanas secundarias situadas en el área de widgets acoplables que rodea al « central widget » en un « QMainWindow ».
El usuario final puede mover las ventanas acopladas dentro de su área actual, trasladarlas a nuevas áreas y hacerlas flotantes (es decir, desacoplarlas). La API de QDockWidget permite al programador restringir la capacidad de los widgets acoplados para moverse, flotar y cerrarse, así como las áreas en las que pueden colocarse.
Apariencia
Un QDockWidget consta de una barra de título y el área de contenido. La barra de título muestra el window title del widget acoplado, un botón para flotar y un botón para cerrar. Dependiendo del estado del QDockWidget, los botones para flotar y cerrar pueden estar desactivados o no mostrarse en absoluto.
El aspecto visual de la barra de título y de los botones depende del estilo de barra de título ( style ) que se utilice.
Un QDockWidget actúa como envoltorio de su widget hijo, establecido mediante setWidget(). Las sugerencias de tamaño personalizadas, los tamaños mínimo y máximo y las políticas de tamaño deben implementarse en el widget hijo. QDockWidget las respetará, ajustando sus propias restricciones para incluir el marco y el título. Las restricciones de tamaño no deben establecerse en el propio QDockWidget, ya que varían en función de si está acoplado o no; un QDockWidget acoplado carece de marco y tiene una barra de título más pequeña.
Nota: En macOS, si el QDockWidget tiene un identificador de ventana nativo (por ejemplo, si se llama a winId() sobre él o sobre el widget hijo), debido a una limitación no será posible arrastrar el widget acoplado al desacoplarlo. Al iniciar el arrastre, el widget acoplado se desacoplará, pero será necesario un segundo arrastre para mover el propio widget acoplado.
Véase también QMainWindow.
Documentación sobre tipos de miembros
enum QDockWidget::DockWidgetFeature
flags QDockWidget::DockWidgetFeatures
| Constante | Valor | Descripción |
|---|---|---|
QDockWidget::DockWidgetClosable | 0x01 | El widget del dock se puede cerrar. |
QDockWidget::DockWidgetMovable | 0x02 | El usuario puede mover el widget acoplado de un acoplamiento a otro. |
QDockWidget::DockWidgetFloatable | 0x04 | El widget acoplado se puede desacoplar de la ventana principal y flotar como una ventana independiente. |
QDockWidget::DockWidgetVerticalTitleBar | 0x08 | El widget acoplado muestra una barra de título vertical en su lado izquierdo. Esto puede utilizarse para aumentar el espacio vertical en un « QMainWindow ». |
QDockWidget::NoDockWidgetFeatures | 0x00 | El widget de acoplamiento no se puede cerrar, mover ni convertir en ventana flotante. |
El tipo `DockWidgetFeatures` es una definición de tipo (`typedef`) para ` QFlags<DockWidgetFeature>`. Almacena una combinación OR de valores de `DockWidgetFeature`.
Documentación de propiedades
allowedAreas : Qt::DockWidgetAreas
Áreas en las que se puede colocar el widget del dock
La ubicación predeterminada es Qt::AllDockWidgetAreas.
Funciones de acceso:
| Qt::DockWidgetAreas | allowedAreas() const |
| void | setAllowedAreas(Qt::DockWidgetAreas areas) |
Señal del notificador:
| void | allowedAreasChanged(Qt::DockWidgetAreas allowedAreas) |
Véase también Qt::DockWidgetArea.
[since 6.9] dockLocation : Qt::DockWidgetArea
Esta propiedad contiene la ubicación actual de acoplamiento, o bien Qt::NoDockLocation si este widget de acoplamiento es flotante o no tiene una ventana principal como padre.
Esta enumeración se introdujo en Qt 6.9.
Funciones de acceso:
| Qt::DockWidgetArea | dockLocation() const |
| void | setDockLocation(Qt::DockWidgetArea area) |
Señal de notificador:
| void | dockLocationChanged(Qt::DockWidgetArea area) |
features : DockWidgetFeatures
Esta propiedad indica si el widget del dock se puede mover, cerrar y colocar de forma flotante
Por defecto, esta propiedad se establece en una combinación de DockWidgetClosable, DockWidgetMovable y DockWidgetFloatable.
Funciones de acceso:
| QDockWidget::DockWidgetFeatures | features() const |
| void | setFeatures(QDockWidget::DockWidgetFeatures features) |
Señal del notificador:
| void | featuresChanged(QDockWidget::DockWidgetFeatures features) |
Véase también DockWidgetFeature.
floating : bool
Esta propiedad se mantiene independientemente de si el widget de acoplamiento es flotante
Un widget de acoplamiento flotante se muestra al usuario como una ventana única e independiente «sobre» su QMainWindow principal, en lugar de estar acoplado en el QMainWindow o en un grupo de widgets de acoplamiento con pestañas.
Los widgets de acoplamiento flotantes se pueden colocar y redimensionar individualmente, tanto mediante programación como con el ratón.
Por defecto, esta propiedad es true.
Cuando esta propiedad cambia, se emite la señal « topLevelChanged() ».
Funciones de acceso:
| bool | isFloating() const |
| void | setFloating(bool floating) |
Señal de notificación:
| void | topLevelChanged(bool topLevel) |
Véase también ` isWindow()` y ` topLevelChanged()`.
windowTitle : QString
Esta propiedad contiene el título (leyenda) del widget del dock
Por defecto, esta propiedad contiene una cadena vacía.
Funciones de acceso:
| QString | windowTitle() const |
| void | setWindowTitle(const QString &) |
Señal del notificador:
| void | windowTitleChanged(const QString &title) |
Documentación de las funciones de miembro
[explicit] QDockWidget::QDockWidget(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())
Crea un QDockWidget con el elemento padre parent y los indicadores de ventana flags. El widget acoplable se colocará en el área de widgets acoplables de la izquierda.
[explicit] QDockWidget::QDockWidget(const QString &title, QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())
Crea un QDockWidget con el parent como padre y los indicadores de ventana flags. El widget acoplable se colocará en el área de widgets acoplables de la izquierda.
El título de la ventana se establece en title. Este título se utiliza cuando el QDockWidget está acoplado y desacoplado. También se utiliza en el menú contextual proporcionado por QMainWindow.
Véase también setWindowTitle().
[virtual noexcept] QDockWidget::~QDockWidget()
Elimina el widget del dock.
[signal] void QDockWidget::allowedAreasChanged(Qt::DockWidgetAreas allowedAreas)
Esta señal se emite cuando cambia la propiedad « allowedAreas ». El parámetro « allowedAreas » proporciona el nuevo valor de la propiedad.
Nota: Señalde notificación para la propiedad allowedAreas.
[override virtual protected] void QDockWidget::changeEvent(QEvent *event)
Reimplementa: ` QWidget::changeEvent` (`QEvent *event)`.
[override virtual protected] void QDockWidget::closeEvent(QCloseEvent *event)
Reimplementa: ` QWidget::closeEvent(QCloseEvent *event)`.
[signal] void QDockWidget::dockLocationChanged(Qt::DockWidgetArea area)
Esta señal se emite cuando el widget del dock se desplaza a otro dock area o se traslada a una ubicación diferente dentro de su área de dock actual. Esto ocurre cuando el widget del dock se desplaza mediante código o cuando el usuario lo arrastra a una nueva ubicación.
Nota: Señalde notificación para la propiedad dockLocation.
Véase también dockLocation() y setDockLocation().
[override virtual protected] bool QDockWidget::event(QEvent *event)
Reimplementa: ` QWidget::event(QEvent *event)`.
[signal] void QDockWidget::featuresChanged(QDockWidget::DockWidgetFeatures features)
Esta señal se emite cuando cambia la propiedad « features ». El parámetro « features » proporciona el nuevo valor de la propiedad.
Nota: Señalde notificación para la propiedad ` features`.
[virtual protected] void QDockWidget::initStyleOption(QStyleOptionDockWidget *option) const
Inicializa ` option ` con los valores de esta página: QDockWidget. Este método resulta útil para las subclases cuando necesitan un ` QStyleOptionDockWidget`, pero no quieren introducir toda la información ellas mismas.
Véase también QStyleOption::initFrom().
bool QDockWidget::isAreaAllowed(Qt::DockWidgetArea area) const
Devuelve « true » si este widget del dock se puede colocar en el « area » indicado; en caso contrario, devuelve « false ».
[override virtual protected] void QDockWidget::paintEvent(QPaintEvent *event)
Reimplementa: QWidget::paintEvent(QPaintEvent *event).
[since 6.9] void QDockWidget::setDockLocation(Qt::DockWidgetArea area)
Asigna este widget acoplable a area. Si está acoplado en otra ubicación de acoplamiento, se desplazará a area. Si está flotante o forma parte de pestañas flotantes, la siguiente llamada a setFloating(false) lo acoplará en area.
Nota: setDockLocation (Qt::NoDockLocation) es equivalente a setFloating(true).
Nota: Funciónsetter para la propiedad dockLocation.
Esta función se introdujo en Qt 6.9.
Véase también dockLocation() y dockLocationChanged().
void QDockWidget::setTitleBarWidget(QWidget *widget)
Establece un objeto ` widget ` arbitrario como barra de título del widget de acoplamiento. Si ` widget ` es ` nullptr`, cualquier widget de barra de título personalizado establecido previamente en el widget de acoplamiento se retira, aunque no se elimina, y en su lugar se utilizará la barra de título predeterminada.
Si se ha establecido un widget de barra de título, QDockWidget no utilizará las decoraciones nativas de la ventana cuando se muestre en modo flotante.
A continuación se ofrecen algunos consejos para implementar barras de título personalizadas:
- Los eventos del ratón que no sean gestionados explícitamente por el widget de la barra de título deben ignorarse llamando a ` QMouseEvent::ignore()`. Estos eventos se propagan entonces al elemento padre ` QDockWidget `, que los gestiona de la forma habitual: desplazándose cuando se arrastra la barra de título, acoplando y desacoplando al hacer doble clic, etc.
- Cuando se establece ` DockWidgetVerticalTitleBar ` en ` QDockWidget`, el widget de la barra de título se reposiciona en consecuencia. En ` resizeEvent()`, la barra de título debe comprobar qué orientación debe adoptar:
QDockWidget *dockWidget = qobject_cast<QDockWidget*>(parentWidget()); if (dockWidget->features() & QDockWidget::DockWidgetVerticalTitleBar) { // I need to be vertical } else { // I need to be horizontal } - El widget de la barra de título debe tener unas funciones válidas QWidget::sizeHint() y QWidget::minimumSizeHint(). Estas funciones deben tener en cuenta la orientación actual de la barra de título.
- No es posible eliminar una barra de título de un widget de acoplamiento. Sin embargo, se puede conseguir un efecto similar estableciendo un QWidget construido por defecto como widget de la barra de título.
Al utilizar qobject_cast() tal y como se muestra arriba, el widget de la barra de título tiene acceso completo a su QDockWidget padre. Por lo tanto, puede realizar operaciones como acoplarse u ocultarse en respuesta a las acciones del usuario.
Véase también ` titleBarWidget()` y ` DockWidgetVerticalTitleBar`.
void QDockWidget::setWidget(QWidget *widget)
Establece el widget del widget del dock en « widget ».
Si el widget del dock está visible cuando se añade widget, debes show() explícitamente.
Ten en cuenta que debes añadir el diseño de « widget » antes de llamar a esta función; de lo contrario, el « widget » no será visible.
Véase también widget().
QWidget *QDockWidget::titleBarWidget() const
Devuelve el widget de barra de título personalizado establecido en QDockWidget, o nullptr si no se ha establecido ninguna barra de título personalizada.
Véase también setTitleBarWidget().
QAction *QDockWidget::toggleViewAction() const
Devuelve una acción que se puede marcar y que se puede añadir a menús y barras de herramientas para que el usuario pueda mostrar o cerrar este widget acoplable.
El texto de la acción se establece como el título de la ventana del widget acoplable.
El objeto ` QAction ` pertenece al ` QDockWidget`. Se eliminará automáticamente cuando se destruya el ` QDockWidget `.
Nota: La acción no se puede utilizar para mostrar u ocultar el widget de acoplamiento mediante programación. Para ello, utilice la propiedad ` visible `.
Véase también QAction::text y QWidget::windowTitle.
[signal] void QDockWidget::topLevelChanged(bool topLevel)
Esta señal se emite cuando cambia la propiedad « floating ». El parámetro « topLevel » es «true» si el widget acoplado está ahora flotante; en caso contrario, es «false».
Nota: Señalde notificación para la propiedad floating.
Véase también isWindow().
[signal] void QDockWidget::visibilityChanged(bool visible)
Esta señal se emite cuando el widget de acoplamiento pasa a estar « visible » (o invisible). Esto ocurre cuando el widget se oculta o se muestra, así como cuando se acopla en un área de acoplamiento con pestañas y su pestaña se selecciona o se deselecciona.
Nota: La señal puede diferir de « QWidget::isVisible()». Esto puede ocurrir si un widget acoplado está minimizado o organizado en pestañas y asociado a una pestaña no seleccionada o inactiva.
QWidget *QDockWidget::widget() const
Devuelve el widget correspondiente al widget del dock. Esta función devuelve cero si no se ha establecido el widget.
Véase también ` setWidget()`.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.