En esta página

QToolButton Class

La clase QToolButton ofrece un botón de acceso rápido a comandos u opciones, que suele utilizarse dentro de un QToolBar. Más...

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

Tipos públicos

enum ToolButtonPopupMode { DelayedPopup, MenuButtonPopup, InstantPopup }

Propiedades

Funciones públicas

QToolButton(QWidget *parent = nullptr)
virtual ~QToolButton()
Qt::ArrowType arrowType() const
bool autoRaise() const
QAction *defaultAction() const
QMenu *menu() const
QToolButton::ToolButtonPopupMode popupMode() const
void setArrowType(Qt::ArrowType type)
void setAutoRaise(bool enable)
void setMenu(QMenu *menu)
void setPopupMode(QToolButton::ToolButtonPopupMode mode)
Qt::ToolButtonStyle toolButtonStyle() const

Funciones públicas reimplementadas

virtual QSize minimumSizeHint() const override
virtual QSize sizeHint() const override

Ranuras públicas

void setDefaultAction(QAction *action)
void setToolButtonStyle(Qt::ToolButtonStyle style)
void showMenu()

Señales

void triggered(QAction *action)

Funciones protegidas

virtual void initStyleOption(QStyleOptionToolButton *option) const

Funciones protegidas reimplementadas

virtual void actionEvent(QActionEvent *event) override
virtual void changeEvent(QEvent *e) override
virtual void checkStateSet() override
virtual void enterEvent(QEnterEvent *e) override
virtual bool event(QEvent *event) override
virtual bool hitButton(const QPoint &pos) const override
virtual void leaveEvent(QEvent *e) override
virtual void mousePressEvent(QMouseEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual void nextCheckState() override
virtual void paintEvent(QPaintEvent *event) override
virtual void timerEvent(QTimerEvent *e) override

Descripción detallada

Un botón de herramienta es un botón especial que permite acceder rápidamente a comandos u opciones específicos. A diferencia de un botón de comando normal, un botón de herramienta no suele mostrar una etiqueta de texto, sino un icono.

Los botones de herramienta se crean normalmente al generar nuevas instancias de ` QAction ` mediante ` QToolBar::addAction()` o al añadir acciones existentes a una barra de herramientas con ` QToolBar::addAction()`. También es posible crear botones de herramienta del mismo modo que cualquier otro widget y colocarlos junto a otros widgets en los diseños.

Un uso clásico de un botón de herramienta es seleccionar herramientas; por ejemplo, la herramienta «lápiz» en un programa de dibujo. Esto se implementaría utilizando un QToolButton como botón de alternancia (véase setCheckable()).

QToolButton admite la función de «auto-raising». En el modo «auto-raising», el botón dibuja un marco 3D solo cuando el ratón se sitúa sobre él. Esta función se activa automáticamente cuando se utiliza un botón dentro de un QToolBar. Se puede modificar con setAutoRaise().

El icono de un botón de herramienta se configura mediante ` QIcon`. Esto permite especificar diferentes mapas de píxeles para el estado desactivado y el estado activo. El mapa de píxeles desactivado se utiliza cuando la funcionalidad del botón no está disponible. El mapa de píxeles activo se muestra cuando el botón se resalta automáticamente porque el puntero del ratón se encuentra sobre él.

El aspecto y las dimensiones del botón se pueden ajustar mediante setToolButtonStyle() y setIconSize(). Cuando se utiliza dentro de un QToolBar en un QMainWindow, el botón se ajusta automáticamente a la configuración de QMainWindow(véase QMainWindow::setToolButtonStyle() y QMainWindow::setIconSize()). En lugar de un icono, un botón de herramienta también puede mostrar un símbolo de flecha, especificado con arrowType.

Un botón de herramienta puede ofrecer opciones adicionales en un menú emergente. El menú emergente se puede configurar mediante ` setMenu()`. Utiliza ` setPopupMode()` para configurar los diferentes modos disponibles para los botones de herramienta con un menú establecido. El modo predeterminado es `DelayedPopupMode`, que a veces se utiliza con el botón «Atrás» de un navegador web. Tras mantener pulsado el botón durante un tiempo, aparece un menú emergente que muestra una lista de las páginas a las que se puede saltar. El tiempo de espera depende del estilo; véase ` QStyle::SH_ToolButton_PopupDelay`.

La barra de herramientas de <span translate=Qt Assistant con botones de herramientas" src="images/assistant-toolbar.png" title="La barra de herramientas de Qt Assistant con botones de herramientas"/>

Qt AssistantLa barra de herramientas contiene botones de herramientas asociados a acciones que se utilizan en otras partes de la ventana principal.

Véase también QPushButton, QToolBar, QMainWindow y QAction.

Documentación sobre tipos de miembros

enum QToolButton::ToolButtonPopupMode

Describe cómo debe aparecer el menú emergente de los botones de herramientas que tienen un conjunto de opciones o contienen una lista de acciones.

ConstanteValorDescripción
QToolButton::DelayedPopup0Tras mantener pulsado el botón de herramienta durante un tiempo determinado (el tiempo de espera depende del estilo; véase QStyle::SH_ToolButton_PopupDelay), se muestra el menú. Un ejemplo típico de aplicación es el botón «Atrás» de las barras de herramientas de algunos navegadores web. Si el usuario hace clic en él, el navegador simplemente vuelve a la página anterior. Si el usuario mantiene pulsado el botón durante un rato, el botón de herramienta muestra un menú que contiene la lista del historial actual
QToolButton::MenuButtonPopup1En este modo, el botón de herramienta muestra una flecha especial para indicar que hay un menú. El menú se muestra al pulsar la parte del botón que contiene la flecha.
QToolButton::InstantPopup2El menú se muestra, sin demora, al pulsar el botón de herramienta. En este modo, no se activa la acción propia del botón.

Documentación de propiedades

arrowType : Qt::ArrowType

Esta propiedad determina si el botón muestra una flecha en lugar de un icono normal

Esto muestra una flecha como icono para el QToolButton.

Por defecto, esta propiedad está establecida en « Qt::NoArrow ».

Funciones de acceso:

Qt::ArrowType arrowType() const
void setArrowType(Qt::ArrowType type)

autoRaise : bool

Esta propiedad se mantiene independientemente de si la función de aumento automático está activada o no.

El valor por defecto es desactivado (es decir, «false»).

Actualmente, esta propiedad se ignora en macOS cuando se utiliza QMacStyle.

Funciones de acceso:

bool autoRaise() const
void setAutoRaise(bool enable)

popupMode : ToolButtonPopupMode

describe cómo se utilizan los menús emergentes con los botones de herramientas

Por defecto, esta propiedad está establecida en « DelayedPopup ».

Funciones de Access:

QToolButton::ToolButtonPopupMode popupMode() const
void setPopupMode(QToolButton::ToolButtonPopupMode mode)

toolButtonStyle : Qt::ToolButtonStyle

Esta propiedad determina si el botón de la herramienta muestra solo un icono, solo texto o texto junto al icono o debajo de él.

El valor predeterminado es « Qt::ToolButtonIconOnly ».

Para que el estilo de los botones de herramienta siga la configuración del sistema, establezca esta propiedad en « Qt::ToolButtonFollowStyle ». En Unix, se utilizarán los ajustes de usuario del entorno de escritorio. En otras plataformas, « Qt::ToolButtonFollowStyle » significa «solo icono».

QToolButton Conecta automáticamente esta ranura a la señal correspondiente en el « QMainWindow » en el que se encuentra.

Funciones de acceso:

Qt::ToolButtonStyle toolButtonStyle() const
void setToolButtonStyle(Qt::ToolButtonStyle style)

Documentación de funciones de miembro

[explicit] QToolButton::QToolButton(QWidget *parent = nullptr)

Crea un botón de herramienta vacío con el elemento padre parent.

[virtual noexcept] QToolButton::~QToolButton()

Destruye el objeto y libera todos los recursos asignados.

[override virtual protected] void QToolButton::actionEvent(QActionEvent *event)

Reimplementa: QWidget::actionEvent(QActionEvent *event).

[override virtual protected] void QToolButton::changeEvent(QEvent *e)

Reimplementa: ` QAbstractButton::changeEvent(QEvent *e)`.

[override virtual protected] void QToolButton::checkStateSet()

Reimplementa: QAbstractButton::checkStateSet().

QAction *QToolButton::defaultAction() const

Devuelve la acción predeterminada.

Véase también setDefaultAction().

[override virtual protected] void QToolButton::enterEvent(QEnterEvent *e)

Reimplementa: QWidget::enterEvent(QEnterEvent *event).

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

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

[override virtual protected] bool QToolButton::hitButton(const QPoint &pos) const

Reimplementa: QAbstractButton::hitButton(const QPoint &pos) const.

[virtual protected] void QToolButton::initStyleOption(QStyleOptionToolButton *option) const

Inicializa ` option ` con los valores de esta página: QToolButton. Este método resulta útil para las subclases cuando necesitan un ` QStyleOptionToolButton`, pero no quieren rellenar toda la información ellas mismas.

Véase también QStyleOption::initFrom().

[override virtual protected] void QToolButton::leaveEvent(QEvent *e)

Reimplementa: ` QWidget::leaveEvent(QEvent *event)`.

Devuelve el menú asociado o nullptr si no se ha definido ningún menú.

Véase también setMenu().

[override virtual] QSize QToolButton::minimumSizeHint() const

Reimplementa una función de acceso para la propiedad: QWidget::minimumSizeHint.

[override virtual protected] void QToolButton::mousePressEvent(QMouseEvent *e)

Reimplementa: QAbstractButton::mousePressEvent(QMouseEvent *e).

[override virtual protected] void QToolButton::mouseReleaseEvent(QMouseEvent *e)

Reimplementa: QAbstractButton::mouseReleaseEvent(QMouseEvent *e).

[override virtual protected] void QToolButton::nextCheckState()

Reimplementa: QAbstractButton::nextCheckState().

[override virtual protected] void QToolButton::paintEvent(QPaintEvent *event)

Reimplementa: QAbstractButton::paintEvent(QPaintEvent *e).

Dibuja el botón en respuesta al evento de dibujo event.

[slot] void QToolButton::setDefaultAction(QAction *action)

Establece la acción predeterminada en « action ».

Si un botón de herramienta tiene una acción predeterminada, dicha acción define las siguientes propiedades del botón:

Otras propiedades, como « autoRepeat », no se ven afectadas por las acciones.

Véase también ` defaultAction()`.

void QToolButton::setMenu(QMenu *menu)

Asocia el « menu » indicado a este botón de la herramienta.

El menú se mostrará según el « popupMode » del botón.

La propiedad del menú no se transfiere al botón de herramienta.

Véase también menu().

[slot] void QToolButton::showMenu()

Muestra (abre en una ventana emergente) el menú emergente asociado. Si no existe dicho menú, esta función no realiza ninguna acción. Esta función no finaliza hasta que el usuario haya cerrado el menú emergente.

[override virtual] QSize QToolButton::sizeHint() const

Reimplementa una función de acceso para la propiedad: QWidget::sizeHint.

[override virtual protected] void QToolButton::timerEvent(QTimerEvent *e)

Reimplementa: ` QAbstractButton::timerEvent(QTimerEvent *e)`.

[signal] void QToolButton::triggered(QAction *action)

Esta señal se emite cuando se activa el « action » indicado.

La acción también puede asociarse a otros elementos de la interfaz de usuario, como elementos de menú y atajos de teclado. Compartir acciones de esta forma contribuye a que la interfaz de usuario sea más coherente y, a menudo, su implementación requiere menos trabajo.

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