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
- arrowType : Qt::ArrowType
- autoRaise : bool
- popupMode : ToolButtonPopupMode
- toolButtonStyle : Qt::ToolButtonStyle
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`.
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.
| Constante | Valor | Descripción |
|---|---|---|
QToolButton::DelayedPopup | 0 | Tras 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::MenuButtonPopup | 1 | En 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::InstantPopup | 2 | El 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)`.
QMenu *QToolButton::menu() const
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:
- checkable
- checked
- enabled
- font
- icon
- popupMode (suponiendo que la acción tenga un menú)
- statusTip
- text
- toolTip
- whatsThis
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.