En esta página

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 ».

Diagrama del widget «dock» dentro de las barras de herramientas y un contenedor para widgets

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

ConstanteValorDescripción
QDockWidget::DockWidgetClosable0x01El widget del dock se puede cerrar.
QDockWidget::DockWidgetMovable0x02El usuario puede mover el widget acoplado de un acoplamiento a otro.
QDockWidget::DockWidgetFloatable0x04El widget acoplado se puede desacoplar de la ventana principal y flotar como una ventana independiente.
QDockWidget::DockWidgetVerticalTitleBar0x08El 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::NoDockWidgetFeatures0x00El 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.