En esta página

QWidgetAction Class

La clase `QWidgetAction` amplía ` QAction ` con una interfaz que permite insertar widgets personalizados en contenedores basados en acciones, como las barras de herramientas. Más...

Encabezado: #include <QWidgetAction>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredado de: QAction

Funciones públicas

QWidgetAction(QObject *parent)
virtual ~QWidgetAction()
QWidget *defaultWidget() const
void releaseWidget(QWidget *widget)
QWidget *requestWidget(QWidget *parent)
void setDefaultWidget(QWidget *widget)

Funciones protegidas

virtual QWidget *createWidget(QWidget *parent)
QList<QWidget *> createdWidgets() const
virtual void deleteWidget(QWidget *widget)

Funciones protegidas reimplementadas

virtual bool event(QEvent *event) override
virtual bool eventFilter(QObject *obj, QEvent *event) override

Descripción detallada

La mayoría de las acciones de una aplicación se representan como elementos de menús o botones en las barras de herramientas. Sin embargo, a veces se necesitan controles más complejos. Por ejemplo, una acción de zoom en un procesador de textos puede realizarse utilizando un ` QComboBox ` en un ` QToolBar`, que presenta una gama de diferentes niveles de zoom. ` QToolBar ` proporciona ` QToolBar::insertWidget()` como función de conveniencia para insertar un único widget. Sin embargo, si se desea implementar una acción que utilice widgets personalizados para su visualización en varios contenedores, es necesario crear una subclase de `QWidgetAction`.

Si se añade un `QWidgetAction`, por ejemplo, a un ` QToolBar `, se llama a ` QWidgetAction::createWidget()`. Las reimplementaciones de esa función deben crear un nuevo widget personalizado con el padre especificado.

Si la acción se elimina de un widget contenedor, se llama a ` QWidgetAction::deleteWidget()` con el widget personalizado creado previamente como argumento. La implementación por defecto oculta el widget y lo elimina mediante ` QObject::deleteLater()`.

Si solo se dispone de un único widget personalizado, se puede establecer como widget por defecto mediante setDefaultWidget(). Ese widget se utilizará entonces si la acción se añade a un QToolBar, o en general a un contenedor de acciones que admita QWidgetAction. Si se añade un `QWidgetAction` con un único widget predeterminado a dos barras de herramientas al mismo tiempo, el widget predeterminado solo se mostrará en la primera barra de herramientas a la que se haya añadido la acción. `QWidgetAction` asume la propiedad del widget predeterminado.

Ten en cuenta que es el propio widget el que debe activar la acción, por ejemplo, reimplementando los controladores de eventos del ratón y llamando a ` QAction::trigger()`.

macOS: Si añades un widget a un menú de la barra de menús de la aplicación en macOS, el widget se añadirá y funcionará, pero con algunas limitaciones:

  1. El widget deja de estar vinculado al QMenu y pasa a estar vinculado a la vista de menú nativa. Si se muestra el menú en otro lugar (por ejemplo, como un menú emergente), el widget no aparecerá allí.
  2. No es posible gestionar el foco ni el teclado en el widget.
  3. Debido al diseño de Apple, el seguimiento del ratón sobre el widget no funciona actualmente.
  4. Conectar la señal « triggered » () a una ranura que abra un cuadro de diálogo modal provocará un fallo en macOS 10.4 (error conocido y reconocido por Apple); una solución alternativa es utilizar una «QueuedConnection» en lugar de una «DirectConnection».

Véase también QAction, QActionGroup y QWidget.

Documentación de las funciones de miembro

[explicit] QWidgetAction::QWidgetAction(QObject *parent)

Crea una acción con « parent ».

[virtual noexcept] QWidgetAction::~QWidgetAction()

Destruye el objeto y libera los recursos asignados.

[virtual protected] QWidget *QWidgetAction::createWidget(QWidget *parent)

Esta función se invoca cada vez que se añade la acción a un widget contenedor que admite widgets personalizados. Si no deseas que se utilice un widget personalizado como representación de la acción en el widget especificado parent, debes devolver el valor 0.

Véase también deleteWidget().

[protected] QList<QWidget *> QWidgetAction::createdWidgets() const

Devuelve la lista de widgets que han utilizado ` createWidget()` y que actualmente están siendo utilizados por los widgets a los que se ha añadido la acción.

QWidget *QWidgetAction::defaultWidget() const

Devuelve el widget predeterminado.

Véase también setDefaultWidget().

[virtual protected] void QWidgetAction::deleteWidget(QWidget *widget)

Esta función se invoca cada vez que se elimina la acción de un widget contenedor que muestra dicha acción mediante un « widget » personalizado creado previamente con la función « createWidget()». La implementación predeterminada oculta el « widget » y programa su eliminación mediante la función « QObject::deleteLater()».

Véase también createWidget().

[override virtual protected] bool QWidgetAction::event(QEvent *event)

Reimplementa: QAction::event(QEvent *e).

[override virtual protected] bool QWidgetAction::eventFilter(QObject *obj, QEvent *event)

Reimplementa: QObject::eventFilter(QObject *watched, QEvent *event).

void QWidgetAction::releaseWidget(QWidget *widget)

Libera el ` widget` especificado.

Los widgets contenedores que admiten acciones llaman a esta función cuando se elimina una acción de un widget.

Véase también requestWidget(), deleteWidget() y defaultWidget().

QWidget *QWidgetAction::requestWidget(QWidget *parent)

Devuelve un widget que representa la acción, con el « parent » indicado.

Los widgets contenedores que admiten acciones pueden llamar a esta función para solicitar un widget como representación visual de la acción.

Véase también releaseWidget(), createWidget() y defaultWidget().

void QWidgetAction::setDefaultWidget(QWidget *widget)

Establece widget como el widget predeterminado. La propiedad se transfiere a QWidgetAction. A menos que una subclase reimplemente createWidget() para devolver un nuevo widget, se utilizará el widget predeterminado cuando un widget contenedor solicite un widget mediante requestWidget().

Véase también defaultWidget().

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