QToolButton Class
La clase QToolButton proporciona un botón de acceso rápido a comandos u opciones, normalmente utilizado dentro de un QToolBar. Más...
| Cabecera: | #include <QToolButton> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Hereda: | 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 proporciona acceso rápido 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 herramientas se crean normalmente cuando se crean nuevas instancias de QAction con QToolBar::addAction() o se añaden acciones existentes a una barra de herramientas con QToolBar::addAction(). También es posible construir botones de herramientas 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 "pluma" en un programa de dibujo. Esto se implementaría usando un QToolButton como botón de alternancia (ver setCheckable()).
QToolButton soporta auto-levantamiento. En modo auto-levantamiento, el botón dibuja un marco 3D sólo cuando el ratón apunta a él. La función se activa automáticamente cuando se utiliza un botón dentro de QToolBar. Cámbiela con setAutoRaise().
El icono de un botón de herramienta se configura como QIcon. Esto permite especificar diferentes mapas de píxeles para los estados desactivado y 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 levanta automáticamente porque el puntero del ratón se sitúa sobre él.
El aspecto y la dimensión del botón se pueden ajustar con 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 puede configurarse con setMenu(). Utilice 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" en un navegador web. Tras mantener pulsado el botón durante un rato, aparece un menú con una lista de posibles páginas a las que 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="Barra de herramientas de Qt Assistant con botones de herramientas"/>
Qt AssistantLa barra de herramientas de 's contiene botones de herramientas que están asociados a acciones utilizadas en otras partes de la ventana principal.
Véase también QPushButton, QToolBar, QMainWindow, y QAction.
Documentación de tipos de miembros
enum QToolButton::ToolButtonPopupMode
Describe cómo debe desplegarse un menú para los botones de herramientas que tienen un conjunto de menús 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, consulte 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 lo pulsa, el navegador simplemente vuelve a la página anterior. Si el usuario mantiene pulsado el botón durante un rato, el botón de herramientas muestra un menú que contiene la lista del historial actual. |
QToolButton::MenuButtonPopup | 1 | En este modo, el botón de herramientas muestra una flecha especial para indicar la presencia de un menú. El menú se muestra cuando se pulsa la parte de la flecha del botón. |
QToolButton::InstantPopup | 2 | El menú se muestra, sin retardo, cuando se pulsa el botón de la herramienta. En este modo, la acción propia del botón no se activa. |
Documentación de propiedades
arrowType : Qt::ArrowType
Esta propiedad indica si el botón muestra una flecha en lugar de un icono normal
Muestra una flecha como icono de 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 indica si la subida automática está activada o no.
Por defecto está desactivada (es decir, es falsa).
Esta propiedad se ignora actualmente en macOS cuando se utiliza QMacStyle.
Funciones de acceso:
| bool | autoRaise() const |
| void | setAutoRaise(bool enable) |
popupMode : ToolButtonPopupMode
describe la forma en que se utilizan los menús emergentes con los botones de herramientas.
Por defecto, esta propiedad está establecida en DelayedPopup.
Funciones de acceso:
| QToolButton::ToolButtonPopupMode | popupMode() const |
| void | setPopupMode(QToolButton::ToolButtonPopupMode mode) |
toolButtonStyle : Qt::ToolButtonStyle
Esta propiedad indica si el botón de herramienta muestra sólo un icono, sólo texto, o texto al lado/debajo del icono.
El valor por defecto es Qt::ToolButtonIconOnly.
Para que el estilo de los botones de herramientas siga la configuración del sistema, establezca esta propiedad a Qt::ToolButtonFollowStyle. En Unix, se utilizará la configuración de usuario del entorno de escritorio. En otras plataformas, Qt::ToolButtonFollowStyle significa sólo icono.
QToolButton conecta automáticamente esta ranura a la señal correspondiente en la dirección QMainWindow en la que se encuentra.
Funciones de acceso:
| Qt::ToolButtonStyle | toolButtonStyle() const |
| void | setToolButtonStyle(Qt::ToolButtonStyle style) |
Documentación de funciones miembro
[explicit] QToolButton::QToolButton(QWidget *parent = nullptr)
Construye un botón de herramienta vacío con el padre parent.
[virtual noexcept] QToolButton::~QToolButton()
Destruye el objeto y libera 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 por defecto.
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 este QToolButton. Este método es útil para subclases cuando necesitan un QStyleOptionToolButton, pero no quieren rellenar toda la información ellos mismos.
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).
Pinta el botón en respuesta al paint event.
[slot] void QToolButton::setDefaultAction(QAction *action)
Establece la acción por defecto en action.
Si un botón de herramienta tiene una acción por defecto, la 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 dado con este botón de herramienta.
El menú se mostrará de acuerdo con el botón popupMode.
La propiedad del menú no se transfiere al botón de herramienta.
Véase también menu().
[slot] void QToolButton::showMenu()
Muestra (hace aparecer) el menú emergente asociado. Si no existe tal menú, esta función no hace nada. Esta función no regresa hasta que el menú emergente haya sido cerrado por el usuario.
[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 dispara el action dado.
La acción también puede estar asociada a otras partes de la interfaz de usuario, como elementos de menú y atajos de teclado. Compartir acciones de esta manera ayuda a que la interfaz de usuario sea más consistente y a menudo es menos trabajo de implementar.
© 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.
