En esta página

QPushButton Class

El widget QPushButton proporciona un botón de comando. Más información...

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

QCommandLinkButton

Propiedades

Funciones públicas

QPushButton(QWidget *parent = nullptr)
QPushButton(const QString &text, QWidget *parent = nullptr)
QPushButton(const QIcon &icon, const QString &text, QWidget *parent = nullptr)
virtual ~QPushButton()
bool autoDefault() const
bool isDefault() const
bool isFlat() const
QMenu *menu() const
void setAutoDefault(bool)
void setDefault(bool)
void setFlat(bool)
void setMenu(QMenu *menu)

Funciones públicas reimplementadas

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

Ranuras públicas

void showMenu()

Funciones protegidas

virtual void initStyleOption(QStyleOptionButton *option) const

Funciones protegidas reimplementadas

virtual bool event(QEvent *e) override
virtual void focusInEvent(QFocusEvent *e) override
virtual void focusOutEvent(QFocusEvent *e) override
virtual bool hitButton(const QPoint &pos) const override
virtual void keyPressEvent(QKeyEvent *e) override
virtual void mouseMoveEvent(QMouseEvent *e) override
virtual void paintEvent(QPaintEvent *) override

Descripción detallada

Botón para crear un nuevo documento

El botón pulsador, o botón de comando, es quizás el widget más utilizado en cualquier interfaz gráfica de usuario. Al pulsar (hacer clic) en un botón se le ordena al ordenador que realice alguna acción o que responda a una pregunta. Los botones típicos son «Aceptar», «Aplicar», «Cancelar», «Cerrar», «Sí», «No» y «Ayuda».

Un botón de comando es rectangular y suele mostrar una etiqueta de texto que describe su acción. Se puede especificar una tecla de acceso rápido anteponiendo un símbolo «&» al carácter deseado en el texto. Por ejemplo:

QPushButton *button = new QPushButton("&Download", this);

En este ejemplo, el atajo es Alt+D. Consulta la documentación de QShortcut para obtener más detalles (para mostrar un símbolo «&» real, utiliza «&&»).

Los botones de pulsación muestran una etiqueta de texto y, opcionalmente, un pequeño icono. Estos se pueden configurar mediante los constructores y modificarse posteriormente utilizando setText() y setIcon(). Si el botón está desactivado, la apariencia del texto y del icono se ajustará según el estilo de la interfaz gráfica de usuario para que el botón parezca «desactivado».

Un botón emite la señal clicked() cuando se activa con el ratón, la barra espaciadora o un atajo de teclado. Conéctate a esta señal para ejecutar la acción del botón. Los botones también proporcionan señales menos habituales, como pressed() y released().

connect(dispenseButton, &QPushButton::clicked, this, &IceCreamMaker::dispense);

Los botones de comando de los cuadros de diálogo son, por defecto, botones predeterminados automáticos, es decir, se convierten automáticamente en el botón predeterminado cuando reciben el foco de entrada del teclado. Un botón predeterminado es un botón que se activa cuando el usuario pulsa la tecla Intro o Retorno en un cuadro de diálogo. Puedes cambiar esto con setAutoDefault(). Ten en cuenta que los botones predeterminados automáticamente reservan un poco de espacio adicional, necesario para dibujar un indicador de botón predeterminado. Si no deseas este espacio alrededor de tus botones, llama a setAutoDefault(false).

Dada su importancia fundamental, el control de botón ha evolucionado para dar cabida a una gran variedad de variantes en la última década. La guía de estilo de Microsoft muestra ahora unos diez estados diferentes de los botones de Windows, y el texto da a entender que hay docenas más si se tienen en cuenta todas las combinaciones de características.

Los modos o estados más importantes son:

  • Disponible o no (atenuado, desactivado).
  • Botón estándar, botón de alternancia o botón de menú.
  • Activado o desactivado (solo para botones de alternancia).
  • Predeterminado o normal. Por lo general, se puede «seleccionar» el botón predeterminado de un cuadro de diálogo con la tecla Intro o Retorno.
  • Repetición automática o no.
  • Pulsado o no.

Como regla general, utiliza un botón cuando la aplicación o la ventana de diálogo realice una acción al hacer clic en él (como Aplicar, Cancelar, Cerrar y Ayuda) y cuando se prevea que el control tenga una forma rectangular ancha con una etiqueta de texto. Los botones pequeños, normalmente cuadrados, que cambian el estado de la ventana en lugar de realizar una acción (como los botones de la esquina superior derecha de QFileDialog) no son botones de comando, sino botones de herramienta. Qt proporciona una clase especial (QToolButton) para estos botones.

Si necesitas un comportamiento de alternancia (véase setCheckable()) o un botón que repita automáticamente la señal de activación al pulsarlo, como las flechas de una barra de desplazamiento (véase setAutoRepeat()), probablemente un botón de comando no sea lo que buscas. En caso de duda, utiliza un botón de herramienta.

Nota: En macOS, cuando el ancho de un botón pulsador es inferior a 50 o su altura es inferior a 30, las esquinas del botón pasan de ser redondeadas a cuadradas. Utiliza la función setMinimumSize() para evitar este comportamiento.

Una variante del botón de comando es el botón de menú. Estos no solo ofrecen un comando, sino varios, ya que al hacer clic en ellos se abre un menú emergente con opciones. Utiliza el método setMenu() para asociar un menú emergente a un botón pulsador.

Otros tipos de botones son los botones de opción (véase QRadioButton) y las casillas de selección (véase QCheckBox).

En Qt, la clase base ` QAbstractButton ` proporciona la mayoría de los modos y otras funciones de la API, mientras que `QPushButton` proporciona la lógica de la interfaz gráfica de usuario. Consulta ` QAbstractButton ` para obtener más información sobre la API.

Véase también QToolButton, QRadioButton y QCheckBox.

Documentación de propiedades

autoDefault : bool

Esta propiedad indica si el botón pulsador es un botón con valor predeterminado automático

Si esta propiedad se establece en «true», el botón es un botón predeterminado automático.

En algunos estilos de interfaz gráfica de usuario, un botón predeterminado se dibuja con un marco adicional a su alrededor, de hasta 3 píxeles o más. Qt mantiene automáticamente este espacio libre alrededor de los botones predeterminados automáticos, es decir, los botones predeterminados automáticos pueden tener un tamaño sugerido ligeramente mayor.

El valor por defecto de esta propiedad es «true» para los botones cuyo padre sea de tipo « QDialog »; en los demás casos, el valor por defecto es «false».

Consulta la propiedad « default » para obtener más detalles sobre cómo interactúan « default » y «auto-default».

Funciones de acceso:

bool autoDefault() const
void setAutoDefault(bool)

default : bool

Esta propiedad indica si el botón pulsador es el botón predeterminado

Los botones predeterminados y los botones predeterminados automáticos determinan qué ocurre cuando el usuario pulsa Intro en un cuadro de diálogo.

Un botón con esta propiedad establecida en «true» (es decir, el botón predeterminado del cuadro de diálogo) se pulsará automáticamente cuando el usuario pulse Intro, con una excepción: si un botón « autoDefault » tiene el foco en ese momento, se pulsará el botón « autoDefault ». Cuando el cuadro de diálogo tiene botones « autoDefault », pero no tiene botón predeterminado, al pulsar «Intro» se pulsará el botón « autoDefault » que tenga el foco en ese momento o, si ningún botón tiene el foco, el siguiente botón « autoDefault » de la cadena de foco.

En un cuadro de diálogo, solo un botón puede ser el botón predeterminado en cada momento. Este botón se muestra entonces con un marco adicional (dependiendo del estilo de la interfaz gráfica de usuario).

El comportamiento del botón predeterminado solo está disponible en los cuadros de diálogo. Siempre se puede hacer clic en los botones desde el teclado pulsando la barra espaciadora cuando el botón tiene el foco.

Si la propiedad «default» se establece en «false» para el botón predeterminado actual mientras el cuadro de diálogo está visible, se asignará automáticamente un nuevo botón predeterminado la próxima vez que un botón del cuadro de diálogo reciba el foco.

El valor predeterminado de esta propiedad es «false».

Funciones de acceso:

bool isDefault() const
void setDefault(bool)

flat : bool

Esta propiedad indica si el borde del botón está resaltado

El valor predeterminado de esta propiedad es «false». Si se establece esta propiedad, la mayoría de los estilos no pintarán el fondo del botón a menos que se pulse el botón. Se puede utilizar « setAutoFillBackground()» para garantizar que el fondo se rellene con el pincel « QPalette::Button ».

Funciones de acceso:

bool isFlat() const
void setFlat(bool)

Documentación de las funciones de miembro

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

Crea un botón sin texto y con un « parent ».

[explicit] QPushButton::QPushButton(const QString &text, QWidget *parent = nullptr)

Crea un botón con el elemento padre « parent » y el texto « text ».

QPushButton::QPushButton(const QIcon &icon, const QString &text, QWidget *parent = nullptr)

Crea un botón con un objeto ` icon `, un ` text` y un ` parent`.

Ten en cuenta que también puedes pasar un objeto ` QPixmap ` como icono (gracias a la conversión de tipos implícita que ofrece C++).

[virtual noexcept] QPushButton::~QPushButton()

Destruye el pulsador.

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

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

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

Reimplementa: ` QAbstractButton::focusInEvent(QFocusEvent *e)`.

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

Reimplementa: QAbstractButton::focusOutEvent(QFocusEvent *e).

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

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

[virtual protected] void QPushButton::initStyleOption(QStyleOptionButton *option) const

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

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

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

Reimplementa: QAbstractButton::keyPressEvent(QKeyEvent *e).

Devuelve el menú emergente asociado al botón o nullptr si no se ha configurado ningún menú emergente.

Véase también setMenu().

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

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

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

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

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

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

void QPushButton::setMenu(QMenu *menu)

Asocia el menú emergente « menu » a este botón. De este modo, el botón se convierte en un botón de menú, lo que, en algunos estilos, hará que aparezca un pequeño triángulo a la derecha del texto del botón.

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

Botón con menú emergente

Un botón con menús emergentes mostrado en el estilo de widget «Fusion».

Véase también menu().

[slot] void QPushButton::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 retorna hasta que el usuario haya cerrado el menú emergente.

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

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

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