En esta página

QAbstractButton Class

La clase `QAbstractButton` es la clase base abstracta de los widgets de botón y proporciona la funcionalidad común a todos ellos. Más...

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

QCheckBox, ` QPushButton`, ` QRadioButton` y QToolButton

Propiedades

Funciones públicas

QAbstractButton(QWidget *parent = nullptr)
virtual ~QAbstractButton()
bool autoExclusive() const
bool autoRepeat() const
int autoRepeatDelay() const
int autoRepeatInterval() const
QButtonGroup *group() const
QIcon icon() const
QSize iconSize() const
bool isCheckable() const
bool isChecked() const
bool isDown() const
void setAutoExclusive(bool)
void setAutoRepeat(bool)
void setAutoRepeatDelay(int)
void setAutoRepeatInterval(int)
void setCheckable(bool)
void setDown(bool)
void setIcon(const QIcon &icon)
void setShortcut(const QKeySequence &key)
void setText(const QString &text)
QKeySequence shortcut() const
QString text() const

Ranuras públicas

void animateClick()
void click()
void setChecked(bool)
void setIconSize(const QSize &size)
void toggle()

Señales

void clicked(bool checked = false)
void pressed()
void released()
void toggled(bool checked)

Funciones protegidas

virtual void checkStateSet()
virtual bool hitButton(const QPoint &pos) const
virtual void nextCheckState()

Funciones protegidas reimplementadas

virtual void changeEvent(QEvent *e) override
virtual bool event(QEvent *e) override
virtual void focusInEvent(QFocusEvent *e) override
virtual void focusOutEvent(QFocusEvent *e) override
virtual void keyPressEvent(QKeyEvent *e) override
virtual void keyReleaseEvent(QKeyEvent *e) override
virtual void mouseMoveEvent(QMouseEvent *e) override
virtual void mousePressEvent(QMouseEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual void paintEvent(QPaintEvent *e) override = 0
virtual void timerEvent(QTimerEvent *e) override

Descripción detallada

Esta clase implementa un botón abstracto. Las subclases de esta clase gestionan las acciones del usuario y especifican cómo se dibuja el botón.

QAbstractButton ofrece soporte tanto para botones de pulsación como para botones de selección (conmutables). Los botones de selección se implementan en las clases QRadioButton y QCheckBox. Los botones de pulsación se implementan en las clases QPushButton y QToolButton; estas también ofrecen comportamiento de conmutación si es necesario.

Cualquier botón puede mostrar una etiqueta que contenga texto y un icono. setText() establece el texto; setIcon() establece el icono. Si un botón está desactivado, su etiqueta cambia para darle al botón un aspecto de «desactivado».

Si el botón es un botón de texto con una cadena que contiene un símbolo «&», QAbstractButton crea automáticamente una tecla de acceso rápido. Por ejemplo:

QPushButton *button = new QPushButton(tr("Ro&ck && Roll"), this);

Se asigna el atajo Alt+C al botón; es decir, cuando el usuario pulse Alt+C, el botón llamará a animateClick(). Consulta la documentación de QShortcut para obtener más detalles. Para mostrar un símbolo «&» real, utiliza «&&».

También puedes definir una tecla de acceso rápido personalizada mediante la función setShortcut(). Esto resulta útil sobre todo para botones que no contienen texto y que, por lo tanto, no pueden tener ningún acceso rápido automático.

button->setIcon(QIcon(":/images/print.png"));
button->setShortcut(tr("Alt+F7"));

Todos los botones proporcionados por Qt (QPushButton, QToolButton, QCheckBox y QRadioButton) pueden mostrar tanto text como icons.

Se puede establecer un botón como botón predeterminado en un cuadro de diálogo mediante QPushButton::setDefault() y QPushButton::setAutoDefault().

QAbstractButton proporciona la mayoría de los estados utilizados para los botones:

  • isDown() indica si el botón está pulsado.
  • isChecked() indica si el botón está marcado. Solo los botones que se pueden marcar pueden marcarse y desmarcarse (véase más abajo).
  • isEnabled() indica si el usuario puede pulsar el botón.

    Nota: A diferencia de otros widgets, los botones derivados de `QAbstractButton` aceptan eventos del ratón y del menú contextual cuando están desactivados.

  • setAutoRepeat() establece si el botón se repetirá automáticamente si el usuario lo mantiene pulsado. autoRepeatDelay y autoRepeatInterval definen cómo se lleva a cabo la repetición automática.
  • setCheckable() establece si el botón es un botón de alternancia o no.

La diferencia entre ` isDown()` y ` isChecked()` es la siguiente. Cuando el usuario hace clic en un botón de alternancia para marcarlo, el botón se pulsa primero y luego se suelta, pasando al estado marcado. Cuando el usuario vuelve a hacer clic en él (para desmarcarlo), el botón pasa primero al estado pulsado y luego al estado desmarcado (tantoisChecked() como isDown() son falsos).

QAbstractButton proporciona cuatro señales:

  1. pressed() se emite cuando se pulsa el botón izquierdo del ratón mientras el cursor se encuentra dentro del botón.
  2. released() se emite cuando se suelta el botón izquierdo del ratón.
  3. clicked() se emite cuando se pulsa y luego se suelta el botón por primera vez, cuando se pulsa la tecla de atajo o cuando se llama a click() o animateClick().
  4. toggled() se emite cuando cambia el estado de un botón de alternancia.

Para crear una subclase de `QAbstractButton`, debes reimplementar al menos ` paintEvent()` para dibujar el contorno del botón y su texto o mapa de píxeles. Por lo general, es recomendable reimplementar también ` sizeHint()`, y en ocasiones ` hitButton()` (para determinar si la pulsación del botón se produce dentro del botón). En el caso de los botones con más de dos estados (como los botones de tres estados), también tendrás que reimplementar checkStateSet() y nextCheckState().

Véase también QButtonGroup.

Documentación de propiedades

autoExclusive : bool

Esta propiedad indica si la exclusividad automática está activada

Si la exclusividad automática está activada, los botones marcables que pertenecen al mismo widget padre se comportan como si formaran parte del mismo grupo de botones exclusivos. En un grupo de botones exclusivos, solo se puede marcar un botón a la vez; al marcar otro botón, se desmarca automáticamente el que estaba marcado anteriormente.

La propiedad no tiene ningún efecto sobre los botones que pertenecen a un grupo de botones.

La propiedad `autoExclusive` está desactivada por defecto, excepto en el caso de los botones de opción.

Funciones de acceso:

bool autoExclusive() const
void setAutoExclusive(bool)

Véase también QRadioButton.

autoRepeat : bool

Esta propiedad indica si la función «autoRepeat» está activada

Si la repetición automática está activada, las señales « pressed()», « released()» y « clicked()» se emiten a intervalos regulares mientras el botón permanece pulsado. La repetición automática está desactivada por defecto. El retraso inicial y el intervalo de repetición se definen en milisegundos mediante « autoRepeatDelay » y « autoRepeatInterval ».

Nota: Si se pulsa un botón mediante una tecla de acceso rápido, la repetición automática se activa y su temporización la gestiona el sistema, no esta clase. Las señales pressed(), released() y clicked() se emitirán como en el caso normal.

Funciones de acceso:

bool autoRepeat() const
void setAutoRepeat(bool)

autoRepeatDelay : int

Esta propiedad define el retardo inicial de la repetición automática

Si se activa la opción « autoRepeat », entonces «autoRepeatDelay» define el retraso inicial, en milisegundos, antes de que se active la repetición automática.

Funciones de acceso:

int autoRepeatDelay() const
void setAutoRepeatDelay(int)

Véase también « autoRepeat » y « autoRepeatInterval ».

autoRepeatInterval : int

Esta propiedad define la duración del intervalo de repetición automática

Si está activada la opción « autoRepeat », entonces «autoRepeatInterval» define la duración del intervalo de repetición automática en milisegundos.

Funciones de acceso:

int autoRepeatInterval() const
void setAutoRepeatInterval(int)

Véase también « autoRepeat » y « autoRepeatDelay ».

checkable : bool

Esta propiedad indica si el botón se puede marcar

Por defecto, el botón no se puede marcar.

Funciones de Access:

bool isCheckable() const
void setCheckable(bool)

Véase también checked.

checked : bool

Esta propiedad indica si el botón está marcado

Solo se pueden marcar los botones que admiten esta opción. Por defecto, el botón está desmarcado.

Funciones de acceso:

bool isChecked() const
void setChecked(bool)

Señal de notificación:

void toggled(bool checked)

Véase también checkable.

down : bool

Esta propiedad indica si el botón está pulsado

Si esta propiedad es « true », el botón está pulsado. Las señales « pressed()» y « clicked()» no se emiten si se establece esta propiedad en «true». El valor por defecto es «false».

Funciones de acceso:

bool isDown() const
void setDown(bool)

icon : QIcon

Esta propiedad contiene el icono que se muestra en el botón

El tamaño predeterminado del icono viene definido por el estilo de la interfaz gráfica de usuario, pero se puede ajustar configurando la propiedad « iconSize ».

Funciones de acceso:

QIcon icon() const
void setIcon(const QIcon &icon)

iconSize : QSize

Esta propiedad almacena el tamaño del icono que se utiliza para este botón.

El tamaño por defecto viene definido por el estilo de la interfaz gráfica de usuario. Se trata del tamaño máximo de los iconos. Los iconos más pequeños no se ampliarán.

Funciones de acceso:

QSize iconSize() const
void setIconSize(const QSize &size)

shortcut : QKeySequence

Esta propiedad contiene el mnemónico asociado al botón

Funciones de acceso:

QKeySequence shortcut() const
void setShortcut(const QKeySequence &key)

text : QString

Esta propiedad contiene el texto que se muestra en el botón

Si el botón no tiene texto, la función text() devolverá una cadena vacía.

Si el texto contiene el carácter «&» (símbolo «y»), se crea automáticamente un atajo para él. El carácter que siga al «&» se utilizará como tecla de atajo. Cualquier atajo anterior se sobrescribirá o se borrará si el texto no define ningún atajo. Consulta la documentación de QShortcut para obtener más detalles. Para mostrar un símbolo «&» real, utiliza «&&».

No hay ningún texto predeterminado.

Funciones de Access:

QString text() const
void setText(const QString &text)

Documentación de funciones de miembro

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

Crea un botón abstracto con un ` parent`.

[virtual noexcept] QAbstractButton::~QAbstractButton()

Elimina el botón.

[slot] void QAbstractButton::animateClick()

Realiza un clic animado: el botón se pulsa inmediatamente y se suelta 100 ms después.

Si se vuelve a llamar a esta función antes de que se suelte el botón, se reinicia el temporizador de liberación.

Se emiten todas las señales asociadas a un clic según corresponda.

Esta función no hace nada si el botón está disabled.

Véase también click().

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

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

[virtual protected] void QAbstractButton::checkStateSet()

Este controlador virtual se invoca cuando se utiliza ` setChecked()`, salvo que se invoque desde dentro de ` nextCheckState()`. Permite a las subclases restablecer los estados intermedios de sus botones.

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

[slot] void QAbstractButton::click()

Realiza un clic.

Se emiten todas las señales habituales asociadas a un clic, según corresponda. Si el botón es de selección, se alterna su estado.

Esta función no hace nada si el botón está disabled.

Véase también animateClick().

[signal] void QAbstractButton::clicked(bool checked = false)

Esta señal se emite cuando se activa el botón (es decir, cuando se pulsa y luego se suelta mientras el cursor del ratón se encuentra dentro del botón), cuando se pulsa la tecla de acceso rápido o cuando se llama a ` click()` o ` animateClick()`. Cabe destacar que esta señal no se emite si se llama a ` setDown()`, ` setChecked()` o ` toggle()`.

Si el botón es de selección, checked es verdadero si el botón está marcado, o falso si no lo está.

Véanse también pressed(), released() y toggled().

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

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

[override virtual protected] void QAbstractButton::focusInEvent(QFocusEvent *e)

Reimplementa: QWidget::focusInEvent(QFocusEvent *event).

[override virtual protected] void QAbstractButton::focusOutEvent(QFocusEvent *e)

Reimplementa: QWidget::focusOutEvent(QFocusEvent *event).

QButtonGroup *QAbstractButton::group() const

Devuelve el grupo al que pertenece este botón.

Si el botón no forma parte de ningún grupo QButtonGroup, esta función devuelve nullptr.

Véase también « QButtonGroup ».

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

Devuelve ` true ` si ` pos ` se encuentra dentro del rectángulo del botón en el que se puede hacer clic; en caso contrario, devuelve ` false`.

Por defecto, el área en la que se puede hacer clic es todo el widget. Las subclases pueden reimplementar esta función para admitir áreas en las que se puede hacer clic de diferentes formas y tamaños.

[override virtual protected] void QAbstractButton::keyPressEvent(QKeyEvent *e)

Reimplementa: ` QWidget::keyPressEvent(QKeyEvent *event)`.

[override virtual protected] void QAbstractButton::keyReleaseEvent(QKeyEvent *e)

Reimplementa: ` QWidget::keyReleaseEvent(QKeyEvent *event)`.

[override virtual protected] void QAbstractButton::mouseMoveEvent(QMouseEvent *e)

Reimplementa: ` QWidget::mouseMoveEvent(QMouseEvent *event)`.

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

Reimplementa: ` QWidget::mousePressEvent(QMouseEvent *event)`.

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

Reimplementa: QWidget::mouseReleaseEvent(QMouseEvent *event).

[virtual protected] void QAbstractButton::nextCheckState()

Este controlador virtual se activa al hacer clic en un botón. La implementación por defecto llama a ` setChecked` (! `isChecked`) si el botón ` isCheckable`. Esto permite a las subclases implementar estados intermedios del botón.

Véase también checkStateSet().

[override pure virtual protected] void QAbstractButton::paintEvent(QPaintEvent *e)

Reimplementa: QWidget::paintEvent(QPaintEvent *event).

[signal] void QAbstractButton::pressed()

Esta señal se emite al pulsar el botón.

Véase también released() y clicked().

[signal] void QAbstractButton::released()

Esta señal se emite al soltar el botón.

Véase también pressed(), clicked() y toggled().

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

Reimplementa: ` QObject::timerEvent(QTimerEvent *event)`.

[slot] void QAbstractButton::toggle()

Cambia el estado de un botón que admite marca.

Véase también checked.

[signal] void QAbstractButton::toggled(bool checked)

Esta señal se emite cada vez que un botón con casilla de selección cambia de estado. « checked » es verdadero si el botón está marcado, o falso si no lo está.

Esto puede deberse a una acción del usuario, a la activación de la ranura ` click()` o a que se haya llamado a ` setChecked()`.

Los estados de los botones de los grupos de botones exclusivos se actualizan antes de que se emita esta señal. Esto significa que las ranuras pueden reaccionar tanto a la señal «off» como a la señal «on» emitidas por los botones del grupo cuyos estados hayan cambiado.

Por ejemplo, se puede implementar una ranura que reaccione a las señales emitidas por los botones recién marcados, pero que ignore las señales de los botones que se han desmarcado, utilizando el siguiente patrón:

void MyWidget::reactToToggle(bool checked)
{
   if (checked) {
      // Examine the new button states.
      ...
   }
}

Los grupos de botones se pueden crear utilizando la clase ` QButtonGroup `, y las actualizaciones de los estados de los botones se pueden supervisar con la señal ` QButtonGroup::buttonClicked()`.

Nota: Señal«Notifier » para la propiedad « checked ».

Véase también checked y clicked().

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