En esta página

QMessageBox Class

La clase QMessageBox proporciona un cuadro de diálogo modal para informar al usuario o para plantearle una pregunta y recibir una respuesta. Más...

Encabezado: #include <QMessageBox>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredan: QDialog

Tipos públicos

enum ButtonRole { InvalidRole, AcceptRole, RejectRole, DestructiveRole, ActionRole, …, ResetRole }
enum Icon { NoIcon, Question, Information, Warning, Critical }
(since 6.6) enum class Option { DontUseNativeDialog }
flags Options
enum StandardButton { Ok, Open, Save, Cancel, Close, …, ButtonMask }
flags StandardButtons

Propiedades

Funciones públicas

QMessageBox(QWidget *parent = nullptr)
QMessageBox(QMessageBox::Icon icon, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = NoButton, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::Dialog | Qt::MSWindowsFixedSizeDialogHint)
virtual ~QMessageBox()
void addButton(QAbstractButton *button, QMessageBox::ButtonRole role)
QPushButton *addButton(QMessageBox::StandardButton button)
QPushButton *addButton(const QString &text, QMessageBox::ButtonRole role)
QAbstractButton *button(QMessageBox::StandardButton which) const
QMessageBox::ButtonRole buttonRole(QAbstractButton *button) const
QList<QAbstractButton *> buttons() const
QCheckBox *checkBox() const
QAbstractButton *clickedButton() const
QPushButton *defaultButton() const
QString detailedText() const
QAbstractButton *escapeButton() const
QMessageBox::Icon icon() const
QPixmap iconPixmap() const
QString informativeText() const
void open(QObject *receiver, const char *member)
QMessageBox::Options options() const
void removeButton(QAbstractButton *button)
void setCheckBox(QCheckBox *cb)
void setDefaultButton(QMessageBox::StandardButton button)
void setDefaultButton(QPushButton *button)
void setDetailedText(const QString &text)
void setEscapeButton(QAbstractButton *button)
void setEscapeButton(QMessageBox::StandardButton button)
void setIcon(QMessageBox::Icon)
void setIconPixmap(const QPixmap &pixmap)
void setInformativeText(const QString &text)
(since 6.6) void setOption(QMessageBox::Option option, bool on = true)
void setOptions(QMessageBox::Options options)
void setStandardButtons(QMessageBox::StandardButtons buttons)
void setText(const QString &text)
void setTextFormat(Qt::TextFormat format)
void setTextInteractionFlags(Qt::TextInteractionFlags flags)
void setWindowModality(Qt::WindowModality windowModality)
void setWindowTitle(const QString &title)
QMessageBox::StandardButton standardButton(QAbstractButton *button) const
QMessageBox::StandardButtons standardButtons() const
(since 6.6) bool testOption(QMessageBox::Option option) const
QString text() const
Qt::TextFormat textFormat() const
Qt::TextInteractionFlags textInteractionFlags() const

Ranuras públicas

virtual int exec() override

Señales

void buttonClicked(QAbstractButton *button)

Miembros públicos estáticos

void about(QWidget *parent, const QString &title, const QString &text)
void aboutQt(QWidget *parent, const QString &title = QString())
QMessageBox::StandardButton critical(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = Ok, QMessageBox::StandardButton defaultButton = NoButton)
QMessageBox::StandardButton information(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = Ok, QMessageBox::StandardButton defaultButton = NoButton)
QMessageBox::StandardButton question(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = StandardButtons(Yes | No), QMessageBox::StandardButton defaultButton = NoButton)
QMessageBox::StandardButton warning(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = Ok, QMessageBox::StandardButton defaultButton = NoButton)

Funciones protegidas reimplementadas

virtual void changeEvent(QEvent *ev) override
virtual void closeEvent(QCloseEvent *e) override
virtual bool event(QEvent *e) override
virtual void keyPressEvent(QKeyEvent *e) override
virtual void resizeEvent(QResizeEvent *event) override
virtual void showEvent(QShowEvent *e) override

Macros

QT_REQUIRE_VERSION(int argc, char **argv, const char *version)

Descripción detallada

Un cuadro de mensaje muestra un « text » principal para alertar al usuario de una situación, un « informative text » para explicar la situación con más detalle y un « detailed text » opcional para proporcionar aún más datos si el usuario lo solicita.

Un cuadro de mensaje también puede mostrar un « icon » y un « standard buttons » para aceptar la respuesta del usuario.

Aunque el parámetro «parent» es opcional, al especificarlo se proporciona una indicación al gestor de ventanas, que puede encargarse entonces del posicionamiento y mantener un orden de apilamiento adecuado de la ventana de diálogo.

Se proporcionan dos API para utilizar QMessageBox: la API basada en propiedades y las funciones estáticas. Llamar a una de las funciones estáticas es el método más sencillo, pero resulta menos flexible que utilizar la API basada en propiedades, y el resultado es menos informativo. Se recomienda utilizar la API basada en propiedades.

La API basada en propiedades

Para utilizar la API basada en propiedades, se debe crear una instancia de QMessageBox, establecer las propiedades deseadas y llamar a ` exec()` para mostrar el mensaje. La configuración más sencilla consiste en establecer únicamente la propiedad ` message text `.

QMessageBox msgBox(this);
msgBox.setText("The document has been modified.");
msgBox.exec();

El usuario debe hacer clic en el botón « OK » para cerrar el cuadro de mensaje. El resto de la interfaz gráfica de usuario queda bloqueada hasta que se cierre el cuadro de mensaje.

Cuadro de mensaje con un mensaje sencillo y un botón «Aceptar»

Un enfoque mejor que limitarse a alertar al usuario de un evento es preguntarle también qué desea hacer al respecto.

Establece la propiedad « standard buttons » en el conjunto de botones que desees como opciones de respuesta del usuario. Los botones se especifican combinando valores de « StandardButtons » mediante el operador OR bit a bit. El orden de visualización de los botones depende de la plataforma. Por ejemplo, en Windows, « Save » se muestra a la izquierda de « Cancel », mientras que en macOS el orden es el inverso. Marca uno de tus botones estándar como « default button ».

La propiedad « informative text » se puede utilizar para añadir contexto adicional que ayude al usuario a elegir la acción adecuada.

QMessageBox msgBox(this);
msgBox.setText("The document has been modified.");
msgBox.setInformativeText("Do you want to save your changes?");
msgBox.setStandardButtons(QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel);
msgBox.setDefaultButton(QMessageBox::Save);
int ret = msgBox.exec();

Cuadro de diálogo con los botones «Guardar», «No guardar» y «Cancelar»

La ranura exec() devuelve el valor StandardButtons del botón en el que se ha hecho clic.

switch (ret) {
    case QMessageBox::Save:
        // Save was clicked
        break;
    case QMessageBox::Discard:
        // Don't Save was clicked
        break;
    case QMessageBox::Cancel:
        // Cancel was clicked
        break;
    default:
        // should never be reached
        break;
}

Para proporcionar al usuario más información que le ayude a elegir la acción adecuada, configura la propiedad « detailed text ». Dependiendo de la plataforma, es posible que el « detailed text » requiera que el usuario haga clic en un botón « Show Details... » para que se muestre.

Cuadro de diálogo «Guardar» con un botón «Mostrar detalles...»

Al hacer clic en el botón « Show Details... », se muestra el texto detallado.

Cuadro de diálogo «Guardar» que muestra el texto detallado

Texto enriquecido y la propiedad «Text Format»

La propiedad detailed text siempre se interpreta como texto sin formato. Las propiedades main text y informative text pueden ser tanto de texto sin formato como de texto enriquecido. Estas cadenas se interpretan según la configuración de la propiedad text format. La configuración predeterminada es auto-text.

Ten en cuenta que, en el caso de algunas cadenas de texto sin formato que contengan metacaracteres XML, la función de texto automático rich text detection test puede fallar, lo que provocaría que tu cadena de texto sin formato se interpretara incorrectamente como texto enriquecido. En estos casos excepcionales, utiliza Qt::convertFromPlainText() para convertir tu cadena de texto sin formato en una cadena de texto enriquecido visualmente equivalente, o configura la propiedad text format explícitamente con setTextFormat().

Niveles de gravedad y las propiedades Icon y Pixmap

QMessageBox admite cuatro niveles de gravedad de mensaje predefinidos, o tipos de mensaje, que en realidad solo se diferencian en el icono predefinido que muestra cada uno. Especifique uno de los cuatro tipos de mensaje predefinidos estableciendo la propiedad icon en uno de los valores de predefined icons. Las siguientes reglas son orientativas:

Icono de signo de interrogación

QuestionPara formular una pregunta durante el funcionamiento normal.

Icono de información

InformationPara proporcionar información sobre el funcionamiento normal.

Icono de advertencia

WarningPara informar de errores no críticos.

Icono de problema grave

CriticalPara informar de errores críticos.

Predefined icons no están definidos por QMessageBox, sino que los proporciona el estilo. El valor predeterminado es No Icon. Por lo demás, los cuadros de mensaje son iguales en todos los casos. Cuando utilices un icono estándar, utiliza el recomendado en la tabla o el recomendado por las directrices de estilo de tu plataforma. Si ninguno de los iconos estándar es adecuado para tu cuadro de mensaje, puedes utilizar un icono personalizado estableciendo la propiedad icon pixmap en lugar de la propiedad icon.

En resumen, para establecer un icono, utilice « setIcon()» para uno de los iconos estándar o « setIconPixmap()» para un icono personalizado.

La API de funciones estáticas

Crear cuadros de mensaje con la API de funciones estáticas, aunque resulta cómodo, es menos flexible que utilizar la API basada en propiedades, ya que las firmas de las funciones estáticas carecen de parámetros para establecer las propiedades ` informative text ` y ` detailed text `. Una solución alternativa a esto ha sido utilizar el parámetro ` title ` como texto principal del cuadro de mensaje y el parámetro ` text ` como texto informativo del cuadro de mensaje. Dado que esto tiene el inconveniente evidente de que el cuadro de mensaje resulta menos legible, las directrices de la plataforma no lo recomiendan. Las Directrices de interfaz de usuario de Microsoft Windows recomiendan utilizar el parámetro application name como window's title, lo que significa que, si se dispone de un texto informativo además del texto principal, este debe concatenarse al parámetro text.

Ten en cuenta que las firmas de las funciones estáticas han cambiado en lo que respecta a sus parámetros de botón, que ahora se utilizan para establecer standard buttons y default button.

Existen funciones estáticas para crear cuadros de mensaje de tipo information(), question(), warning() y critical().

int ret = QMessageBox::warning(this, tr("My Application"),
                               tr("The document has been modified.\n"
                                  "Do you want to save your changes?"),
                               QMessageBox::Save | QMessageBox::Discard
                               | QMessageBox::Cancel,
                               QMessageBox::Save);

El ejemplo «Standard Dialogs » muestra cómo utilizar QMessageBox y los demás cuadros de diálogo integrados en Qt.

Uso avanzado

Si standard buttons no es lo suficientemente flexible para tu cuadro de mensaje, puedes utilizar la sobrecarga addButton() que toma un texto y un ButtonRole para añadir botones personalizados. QMessageBox utiliza ButtonRole para determinar el orden de los botones en pantalla (que varía según la plataforma). Puedes comprobar el valor de clickedButton() tras llamar a exec(). Por ejemplo,

QMessageBox msgBox(this);
QPushButton *connectButton = msgBox.addButton(tr("Connect"), QMessageBox::ActionRole);
QPushButton *abortButton = msgBox.addButton(QMessageBox::Abort);

msgBox.exec();

if (msgBox.clickedButton() == connectButton) {
    // connect
} else if (msgBox.clickedButton() == abortButton) {
    // abort
}

Teclas predeterminadas y de escape

El botón por defecto (es decir, el botón que se activa al pulsar Enter ) se puede especificar mediante setDefaultButton(). Si no se especifica ningún botón por defecto, QMessageBox intenta encontrar uno basándose en el button roles de los botones utilizados en el cuadro de mensaje.

El botón de salida (el botón que se activa al pulsar Esc ) se puede especificar mediante setEscapeButton(). Si no se especifica ningún botón de salida, QMessageBox intenta encontrar uno siguiendo estas reglas:

  1. Si solo hay un botón, es el que se activa al pulsar « Esc ».
  2. Si hay un botón « Cancel », es el botón que se activa al pulsar « Esc ».
  3. Si hay exactamente un botón que tenga o bien el « the Reject role » o bien el « the No role », es el botón que se activa al pulsar « Esc ».

Cuando no se puede determinar un botón de salida mediante estas reglas, al pulsar Esc no ocurre nada.

Véase también « QDialogButtonBox » y «Ejemplo de diálogos estándar».

Documentación sobre tipos de miembro

enum QMessageBox::ButtonRole

Esta enumeración describe las funciones que se pueden utilizar para definir los botones del cuadro de botones. Las combinaciones de estas funciones se utilizan como indicadores para describir diferentes aspectos de su comportamiento.

ConstanteValorDescripción
QMessageBox::InvalidRole-1El botón no es válido.
QMessageBox::AcceptRole0Al hacer clic en el botón, se acepta el cuadro de diálogo (p. ej., «Aceptar»).
QMessageBox::RejectRole1Al hacer clic en el botón, se rechaza el cuadro de diálogo (p. ej., «Cancelar»).
QMessageBox::DestructiveRole2Al hacer clic en el botón se produce un cambio irreversible (p. ej., al descartar cambios) y se cierra el cuadro de diálogo.
QMessageBox::ActionRole3Al hacer clic en el botón se producen cambios en los elementos del cuadro de diálogo.
QMessageBox::HelpRole4Se puede hacer clic en el botón para solicitar ayuda.
QMessageBox::YesRole5El botón es similar a un botón de «Sí».
QMessageBox::NoRole6El botón es similar a uno de «No».
QMessageBox::ApplyRole8El botón aplica los cambios actuales.
QMessageBox::ResetRole7El botón restablece los campos del cuadro de diálogo a sus valores predeterminados.

Véase también StandardButton.

enum QMessageBox::Icon

Esta enumeración tiene los siguientes valores:

ConstanteValorDescripción
QMessageBox::NoIcon0El cuadro de mensaje no tiene ningún icono.
QMessageBox::Question4Un icono que indica que el mensaje plantea una pregunta.
QMessageBox::Information1Un icono que indica que el mensaje no tiene nada de extraordinario.
QMessageBox::Warning2Un icono que indica que el mensaje es una advertencia, pero que se puede solucionar.
QMessageBox::Critical3Un icono que indique que el mensaje representa un problema crítico.

[since 6.6] enum class QMessageBox::Option
flags QMessageBox::Options

ConstanteValorDescripción
QMessageBox::Option::DontUseNativeDialog0x00000001No utilices el cuadro de diálogo de mensajes nativo.

Esta enumeración se introdujo en Qt 6.6.

El tipo «Options» es una definición de tipo (typedef) para QFlags<Option>. Almacena una combinación OR de valores de «Option».

enum QMessageBox::StandardButton
flags QMessageBox::StandardButtons

Estas enumeraciones describen los indicadores de los botones estándar. Cada botón tiene un valor definido en ButtonRole.

ConstanteValorDescripción
QMessageBox::Ok0x00000400Un botón «OK» definido con el AcceptRole.
QMessageBox::Open0x00002000Un botón «Abrir» definido con la AcceptRole.
QMessageBox::Save0x00000800Un botón «Guardar» definido con la función « AcceptRole ».
QMessageBox::Cancel0x00400000Un botón «Cancelar» definido con el RejectRole.
QMessageBox::Close0x00200000Un botón «Cerrar» definido con el RejectRole.
QMessageBox::Discard0x00800000Un botón «Descartar» o «No guardar», dependiendo de la plataforma, definido con la propiedad ` DestructiveRole`.
QMessageBox::Apply0x02000000Un botón «Aplicar» definido con la función ` ApplyRole`.
QMessageBox::Reset0x04000000Un botón «Restablecer» definido con la función ` ResetRole`.
QMessageBox::RestoreDefaults0x08000000Un botón «Restablecer valores predeterminados» definido con la propiedad ` ResetRole`.
QMessageBox::Help0x01000000Un botón «Ayuda» definido con HelpRole.
QMessageBox::SaveAll0x00001000Un botón «Guardar todo» definido con el AcceptRole.
QMessageBox::Yes0x00004000Un botón «Sí» definido con la función ` YesRole`.
QMessageBox::YesToAll0x00008000Un botón «Sí a todo» definido con el YesRole.
QMessageBox::No0x00010000Un botón «No» definido con el NoRole.
QMessageBox::NoToAll0x00020000Un botón «No a todo» definido con el NoRole.
QMessageBox::Abort0x00040000Un botón «Cancelar» definido con la propiedad ` RejectRole`.
QMessageBox::Retry0x00080000Un botón «Reintentar» definido con el AcceptRole.
QMessageBox::Ignore0x00100000Un botón «Ignorar» definido con el AcceptRole.
QMessageBox::NoButton0x00000000Un botón no válido.

Los siguientes valores están obsoletos:

ConstanteValorDescripción
QMessageBox::YesAllYesToAllUtiliza «YesToAll» en su lugar.
QMessageBox::NoAllNoToAllUtilice «NoToAll» en su lugar.
QMessageBox::Default0x00000100Utiliza en su lugar el argumento « defaultButton » de « information()», « warning()», etc., o llama a « setDefaultButton()».
QMessageBox::Escape0x00000200Llama en su lugar a setEscapeButton().
QMessageBox::FlagMask0x00000300 
QMessageBox::ButtonMask~FlagMask 

El tipo StandardButtons es un typedef para QFlags<StandardButton>. Almacena una combinación OR de valores de StandardButton.

Véase también ButtonRole y standardButtons.

Documentación de propiedades

detailedText : QString

Esta propiedad contiene el texto que se mostrará en el área de detalles.

El texto se interpretará como texto sin formato.

Por defecto, esta propiedad contiene una cadena vacía.

Funciones de acceso:

QString detailedText() const
void setDetailedText(const QString &text)

Véase también QMessageBox::text y QMessageBox::informativeText.

icon : Icon

Esta propiedad contiene el icono del cuadro de mensaje

El icono del cuadro de mensaje se puede especificar con uno de los siguientes valores:

El valor predeterminado es « QMessageBox::NoIcon ».

El mapa de píxeles utilizado para mostrar el icono real depende del valor actual de ` GUI style`. También puedes establecer un mapa de píxeles personalizado para el icono configurando la propiedad ` icon pixmap `.

Funciones de Access:

QMessageBox::Icon icon() const
void setIcon(QMessageBox::Icon)

Véase también iconPixmap.

iconPixmap : QPixmap

Esta propiedad contiene el icono actual

El icono que utiliza actualmente el cuadro de mensaje. Ten en cuenta que a menudo resulta difícil dibujar un mapa de píxeles que se vea bien en todos los estilos de interfaz gráfica de usuario; es posible que quieras proporcionar un mapa de píxeles diferente para cada plataforma.

Por defecto, esta propiedad no está definida.

Funciones de acceso:

QPixmap iconPixmap() const
void setIconPixmap(const QPixmap &pixmap)

Véase también icon.

informativeText : QString

Esta propiedad contiene el texto informativo que ofrece una descripción más detallada del mensaje

El texto informativo puede utilizarse para ampliar la text() y ofrecer más información al usuario, por ejemplo, describiendo las consecuencias de la situación o sugiriendo soluciones alternativas.

El texto se interpretará como texto sin formato o como texto enriquecido, dependiendo de la configuración del formato de texto (QMessageBox::textFormat). La configuración predeterminada es Qt::AutoText, es decir, el cuadro de mensaje intentará detectar automáticamente el formato del texto.

Por defecto, esta propiedad contiene una cadena vacía.

Funciones de acceso:

QString informativeText() const
void setInformativeText(const QString &text)

Véase también textFormat, QMessageBox::text y QMessageBox::detailedText.

[since 6.6] options : Options

Opciones que afectan al aspecto y la presentación del cuadro de diálogo.

Por defecto, estas opciones están desactivadas.

La opción « Option::DontUseNativeDialog » debe activarse antes de modificar las propiedades del cuadro de diálogo o de mostrarlo.

No se garantiza que la configuración de las opciones mientras el cuadro de diálogo está visible tenga un efecto inmediato en el mismo.

Establecer opciones después de cambiar otras propiedades puede hacer que estos valores no surtan efecto.

Esta enumeración se introdujo en Qt 6.6.

Funciones de acceso:

QMessageBox::Options options() const
void setOptions(QMessageBox::Options options)

Véase también setOption() y testOption().

standardButtons : StandardButtons

Conjunto de botones estándar del cuadro de mensaje

Esta propiedad controla qué botones estándar utiliza el cuadro de mensaje.

De forma predeterminada, esta propiedad no contiene ningún botón estándar.

Funciones de Access:

QMessageBox::StandardButtons standardButtons() const
void setStandardButtons(QMessageBox::StandardButtons buttons)

Véase también addButton().

text : QString

Esta propiedad contiene el texto del cuadro de mensaje que se va a mostrar.

El texto debe ser una frase breve que describa la situación, formulada idealmente como una afirmación neutra o una pregunta que incite a la acción.

El texto se interpretará como texto sin formato o como texto enriquecido, dependiendo de la configuración del formato de texto (QMessageBox::textFormat). La configuración predeterminada es « Qt::AutoText », es decir, el cuadro de mensaje intentará detectar automáticamente el formato del texto.

El valor por defecto de esta propiedad es una cadena vacía.

Funciones de acceso:

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

Véase también textFormat, QMessageBox::informativeText y QMessageBox::detailedText.

textFormat : Qt::TextFormat

Esta propiedad define el formato del texto que se muestra en el cuadro de mensaje

El formato de texto actual utilizado por el cuadro de mensaje. Consulte la enumeración Qt::TextFormat para obtener una explicación de las opciones posibles.

El formato predeterminado es « Qt::AutoText ».

Funciones de Access:

Qt::TextFormat textFormat() const
void setTextFormat(Qt::TextFormat format)

Véase también setText().

textInteractionFlags : Qt::TextInteractionFlags

Especifica cómo debe interactuar el título del cuadro de mensaje con la entrada del usuario.

El valor predeterminado depende del estilo.

Funciones de Access:

Qt::TextInteractionFlags textInteractionFlags() const
void setTextInteractionFlags(Qt::TextInteractionFlags flags)

Véase también QStyle::SH_MessageBox_TextInteractionFlags.

Documentación de funciones de miembro

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

Crea un cuadro de diálogo « application modal » sin texto ni botones. Se pasa « parent » al constructor « QDialog ».

La modalidad de la ventana se puede anular mediante ` setWindowModality()` antes de llamar a ` show()`.

Nota: El uso de open() o exec() para mostrar el cuadro de mensaje afecta a la modalidad de la ventana. Consulta la documentación detallada de cada función para obtener más información.

En macOS, si desea que su cuadro de mensaje aparezca como un « Qt::Sheet » de su « parent », establezca el parámetro « window modality » del cuadro de mensaje en « Qt::WindowModal » o utilice « open()». De lo contrario, el cuadro de mensaje será un cuadro de diálogo estándar.

Véase también setWindowTitle(), setText(), setIcon(), setStandardButtons() y setWindowModality().

QMessageBox::QMessageBox(QMessageBox::Icon icon, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = NoButton, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::Dialog | Qt::MSWindowsFixedSizeDialogHint)

Crea un cuadro de diálogo de tipo « application modal » con los siguientes elementos: « icon », « title », « text » y el elemento estándar « buttons ». Se pueden añadir botones estándar o personalizados en cualquier momento mediante la función « addButton()». Los argumentos « parent » y « f » se pasan al constructor « QDialog ».

La modalidad de la ventana se puede anular mediante setWindowModality() antes de llamar a show().

Nota: El uso de open() o exec() para mostrar el cuadro de mensaje afecta a la modalidad de la ventana. Consulta la documentación detallada de cada función para obtener más información.

En macOS, si parent no es nullptr y desea que su cuadro de mensaje aparezca como un « Qt::Sheet » de ese elemento padre, establezca el parámetro « window modality » del cuadro de mensaje en « Qt::WindowModal » (valor por defecto). De lo contrario, el cuadro de mensaje será un cuadro de diálogo estándar.

Véanse también setWindowTitle(), setText(), setIcon(), setStandardButtons() y setWindowModality().

[virtual noexcept] QMessageBox::~QMessageBox()

Elimina el cuadro de mensaje.

[static] void QMessageBox::about(QWidget *parent, const QString &title, const QString &text)

Muestra un cuadro de información sencillo con el título « title » y el texto « text ». El elemento padre del cuadro de información es « parent ».

La función `about()` busca un icono adecuado en cuatro ubicaciones:

  1. Da prioridad a parent->icon() si existe.
  2. Si no es así, prueba con el widget de nivel superior que contiene « parent ».
  3. Si eso falla, prueba con el active window.
  4. Como último recurso, utiliza el icono de Información.

El cuadro «Acerca de» tiene un único botón con la etiqueta «Aceptar».

En macOS, el cuadro «Acerca de» aparece como una ventana no modal; en otras plataformas, actualmente es modal para la aplicación.

Véase también QWidget::windowIcon() y QApplication::activeWindow().

[static] void QMessageBox::aboutQt(QWidget *parent, const QString &title = QString())

Muestra un cuadro de mensaje sencillo sobre Qt, con el texto « title » y centrado en « parent » (si « parent » no es « nullptr »). El mensaje incluye el número de versión de Qt que utiliza la aplicación.

Esto resulta útil para incluirlo en el menú « Help » de una aplicación, tal y como se muestra en el ejemplo «Menus ».

QApplication proporciona esta funcionalidad como una ranura.

En macOS, el cuadro «aboutQt» aparece como una ventana no modal; en otras plataformas, actualmente es modal para la aplicación.

Véase también « QApplication::aboutQt » ().

void QMessageBox::addButton(QAbstractButton *button, QMessageBox::ButtonRole role)

Añade el button indicado al cuadro de mensaje con el role especificado.

Véanse también removeButton(), button() y setStandardButtons().

QPushButton *QMessageBox::addButton(QMessageBox::StandardButton button)

Añade un « button » estándar al cuadro de mensaje si es válido hacerlo, y devuelve el botón pulsador.

Esta es una función sobrecargada.

Véase también setStandardButtons().

QPushButton *QMessageBox::addButton(const QString &text, QMessageBox::ButtonRole role)

Crea un botón con el texto dado text, lo añade al cuadro de mensaje correspondiente al role especificado y lo devuelve.

Esta es una función sobrecargada.

QAbstractButton *QMessageBox::button(QMessageBox::StandardButton which) const

Devuelve un puntero correspondiente al botón estándar « which », o « nullptr » si el botón estándar no existe en este cuadro de mensaje.

Nota: Es posible quelos cambios realizados en las propiedades del botón devuelto no se reflejen en las implementaciones nativas del cuadro de diálogo. Para personalizar los botones del cuadro de diálogo, añade en su lugar un custom button o un button title, o bien configura la opción Option::DontUseNativeDialog.

Véase también standardButtons y standardButton().

[signal] void QMessageBox::buttonClicked(QAbstractButton *button)

Esta señal se emite cada vez que se pulsa un botón dentro de ` QMessageBox`. El botón pulsado se devuelve en ` button`.

QMessageBox::ButtonRole QMessageBox::buttonRole(QAbstractButton *button) const

Devuelve el rol de botón para el ` button` especificado. Esta función devuelve ` InvalidRole ` si ` button ` es ` nullptr ` o no se ha añadido al cuadro de mensaje.

Véase también buttons() y addButton().

QList<QAbstractButton *> QMessageBox::buttons() const

Devuelve una lista de todos los botones que se han añadido al cuadro de mensaje.

Véase también buttonRole(), addButton() y removeButton().

[override virtual protected] void QMessageBox::changeEvent(QEvent *ev)

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

QCheckBox *QMessageBox::checkBox() const

Devuelve la casilla de selección que se muestra en el cuadro de diálogo. El valor es « nullptr » si no hay ninguna casilla marcada.

Véase también setCheckBox().

QAbstractButton *QMessageBox::clickedButton() const

Devuelve el botón en el que ha hecho clic el usuario, o ` nullptr ` si el usuario ha pulsado la tecla ` Esc ` y no se ha establecido ningún ` escape button `.

Si aún no se ha llamado a exec(), devuelve nullptr.

Ejemplo:

QMessageBox messageBox(this);
QAbstractButton *disconnectButton =
      messageBox.addButton(tr("Disconnect"), QMessageBox::ActionRole);
//...
messageBox.exec();
if (messageBox.clickedButton() == disconnectButton) {
    //...
}

Véase también standardButton() y button().

[override virtual protected] void QMessageBox::closeEvent(QCloseEvent *e)

Reimplementa: ` QDialog::closeEvent(QCloseEvent *e)`.

[static] QMessageBox::StandardButton QMessageBox::critical(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = Ok, QMessageBox::StandardButton defaultButton = NoButton)

Abre un cuadro de mensaje crítico con los valores « title » y « text » indicados, situado delante del widget « parent » especificado.

Los buttons estándar se añaden al cuadro de mensaje. defaultButton especifica el botón que se utiliza al pulsar Enter. defaultButton debe hacer referencia a un botón que se haya indicado en buttons. Si defaultButton es QMessageBox::NoButton, QMessageBox elige automáticamente un valor por defecto adecuado.

Devuelve la identidad del botón estándar sobre el que se ha hecho clic. Si, en cambio, se ha pulsado Esc, se devuelve escape button.

El cuadro de mensaje es un cuadro de diálogo application modal.

Advertencia: No elimines ` parent ` durante la ejecución del cuadro de diálogo. Si deseas hacerlo, debes crear el cuadro de diálogo tú mismo utilizando uno de los constructores de ` QMessageBox `.

Véase también question(), warning() y information().

QPushButton *QMessageBox::defaultButton() const

Devuelve el botón que debe ser el « default button » del cuadro de mensaje. Devuelve nullptr si no se ha establecido ningún botón predeterminado.

Véanse también setDefaultButton(), addButton() y QPushButton::setDefault().

QAbstractButton *QMessageBox::escapeButton() const

Devuelve el botón que se activa al pulsar la tecla Escape.

Por defecto, QMessageBox intenta detectar automáticamente un botón de escape de la siguiente manera:

  1. Si solo hay un botón, se convierte en el botón de escape.
  2. Si hay un botón « Cancel », se convierte en el botón de escape.
  3. Solo en macOS, si hay exactamente un botón con la función « QMessageBox::RejectRole », se convierte en el botón de escape.

Cuando no se ha podido detectar automáticamente un botón de salida, pulsar « Esc » no tiene ningún efecto.

Véase también « setEscapeButton()» y « addButton()».

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

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

[override virtual slot] int QMessageBox::exec()

Reimplementa: ` QDialog::exec()`.

Muestra el cuadro de mensaje como un ` modal dialog`, bloqueando la ejecución hasta que el usuario lo cierre.

Al utilizar un ` QMessageBox ` con botones estándar, esta función devuelve un valor ` StandardButton ` que indica el botón estándar en el que se ha hecho clic. Al utilizar ` QMessageBox ` con botones personalizados, esta función devuelve un valor opaco; utilice ` clickedButton()` para determinar en qué botón se ha hecho clic.

Nota: La función result() también devuelve un valor StandardButton en lugar de QDialog::DialogCode.

Los usuarios no pueden interactuar con ninguna otra ventana de la misma aplicación hasta que cierren el cuadro de diálogo, ya sea haciendo clic en un botón o utilizando un mecanismo proporcionado por el sistema de ventanas.

Véase también show() y result().

[static] QMessageBox::StandardButton QMessageBox::information(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = Ok, QMessageBox::StandardButton defaultButton = NoButton)

Abre un cuadro de mensaje informativo con los valores « title » y « text » indicados delante del widget « parent » especificado.

Los buttons estándar se añaden al cuadro de mensaje. defaultButton especifica el botón que se utiliza al pulsar Enter. defaultButton debe hacer referencia a un botón que se haya indicado en buttons. Si defaultButton es QMessageBox::NoButton, QMessageBox elige automáticamente un valor por defecto adecuado.

Devuelve la identidad del botón estándar sobre el que se ha hecho clic. Si, en cambio, se ha pulsado Esc, se devuelve el escape button.

El cuadro de mensaje es un cuadro de diálogo application modal.

Advertencia: No elimines ` parent ` durante la ejecución del cuadro de diálogo. Si deseas hacerlo, debes crear el cuadro de diálogo tú mismo utilizando uno de los constructores de ` QMessageBox `.

Véase también question(), warning() y critical().

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

Reimplementa: ` QDialog::keyPressEvent(QKeyEvent *e)`.

void QMessageBox::open(QObject *receiver, const char *member)

Abre el cuadro de diálogo y conecta su señal « finished()» o « buttonClicked()» a la ranura especificada en « receiver » y « member ». Si la ranura de « member » tiene un puntero como primer parámetro, la conexión se establece con « buttonClicked()»; en caso contrario, la conexión se establece con « finished()».

La señal se desconectará de la ranura cuando se cierre el cuadro de diálogo.

[static] QMessageBox::StandardButton QMessageBox::question(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = StandardButtons(Yes | No), QMessageBox::StandardButton defaultButton = NoButton)

Abre un cuadro de diálogo de pregunta con los valores « title » y « text » indicados, situado delante del widget « parent » especificado.

Los valores predeterminados de « buttons » se añaden al cuadro de mensaje. « defaultButton » especifica el botón que se utilizará al pulsar « Enter ». « defaultButton » debe hacer referencia a un botón que se haya indicado en « buttons ». Si « defaultButton » es « QMessageBox::NoButton », « QMessageBox » elige automáticamente un valor predeterminado adecuado.

Devuelve la identidad del botón estándar sobre el que se ha hecho clic. Si, en cambio, se ha pulsado Esc, se devuelve el escape button.

El cuadro de mensaje es un cuadro de diálogo de tipo « application modal ».

Advertencia: No elimines ` parent ` durante la ejecución del cuadro de diálogo. Si deseas hacerlo, debes crear el cuadro de diálogo tú mismo utilizando uno de los constructores de ` QMessageBox `.

Véase también information(), warning() y critical().

void QMessageBox::removeButton(QAbstractButton *button)

Elimina « button » del cuadro de botones sin borrarlo.

Véase también addButton() y setStandardButtons().

[override virtual protected] void QMessageBox::resizeEvent(QResizeEvent *event)

Reimplementa: ` QDialog::resizeEvent` (`QResizeEvent *`).

void QMessageBox::setCheckBox(QCheckBox *cb)

Establece la casilla de selección « cb » en el cuadro de diálogo de mensaje. El cuadro de mensaje asume la propiedad de la casilla de selección. El argumento « cb » puede ser « nullptr » para eliminar una casilla de selección existente del cuadro de mensaje.

Véase también checkBox().

void QMessageBox::setDefaultButton(QMessageBox::StandardButton button)

Establece el campo « default button » del cuadro de mensaje en « button ».

Véanse también defaultButton(), addButton() y QPushButton::setDefault().

void QMessageBox::setDefaultButton(QPushButton *button)

Establece el valor de « default button » del cuadro de mensaje en « button ».

Véase también addButton() y QPushButton::setDefault().

void QMessageBox::setEscapeButton(QAbstractButton *button)

Establece el botón que se activa al pulsar la tecla « Escape » en « button ».

Véase también escapeButton(), addButton() y clickedButton().

void QMessageBox::setEscapeButton(QMessageBox::StandardButton button)

Establece los botones que se activan al pulsar la tecla « Escape » en « button ».

Véase también addButton() y clickedButton().

[since 6.6] void QMessageBox::setOption(QMessageBox::Option option, bool on = true)

Establece la opción « option » para que esté activada si « on » es «true»; en caso contrario, desactiva la opción « option ».

Las opciones (en particular la opción « Option::DontUseNativeDialog ») deben configurarse antes de mostrar el cuadro de diálogo.

No se garantiza que la configuración de las opciones mientras el cuadro de diálogo está visible tenga un efecto inmediato en el mismo.

Establecer opciones después de cambiar otras propiedades puede hacer que estos valores no surtan efecto.

Esta función se introdujo en Qt 6.6.

Véase también options y testOption().

void QMessageBox::setWindowModality(Qt::WindowModality windowModality)

Esta función sobrescribe a ` QWidget::setWindowModality()`.

Establece la modalidad del cuadro de mensaje en « windowModality ».

En macOS, si la modalidad se establece en « Qt::WindowModal » y el cuadro de mensaje tiene un elemento padre, dicho cuadro de mensaje será un « Qt::Sheet »; de lo contrario, será un cuadro de diálogo estándar.

void QMessageBox::setWindowTitle(const QString &title)

Esta función es una versión alternativa de ` QWidget::setWindowTitle()`.

Establece el título del cuadro de mensaje como « title ». En macOS, se ignora el título de la ventana (tal y como exigen las directrices de macOS).

[override virtual protected] void QMessageBox::showEvent(QShowEvent *e)

Reimplementa: QDialog::showEvent(QShowEvent *event).

QMessageBox::StandardButton QMessageBox::standardButton(QAbstractButton *button) const

Devuelve el valor de la enumeración de botones estándar correspondiente al button dado, o bien NoButton si el button dado no es un botón estándar.

Véase también button() y standardButtons().

[since 6.6] bool QMessageBox::testOption(QMessageBox::Option option) const

Devuelve « true » si el « option » indicado está activado; en caso contrario, devuelve «false».

Esta función se introdujo en Qt 6.6.

Véase también options y setOption().

[static] QMessageBox::StandardButton QMessageBox::warning(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = Ok, QMessageBox::StandardButton defaultButton = NoButton)

Abre un cuadro de mensaje de advertencia con los valores « title » y « text » indicados, situado delante del widget « parent » especificado.

Los buttons estándar se añaden al cuadro de mensaje. defaultButton especifica el botón que se utiliza al pulsar Enter. defaultButton debe hacer referencia a un botón que se haya indicado en buttons. Si defaultButton es QMessageBox::NoButton, QMessageBox elige automáticamente un valor por defecto adecuado.

Devuelve la identidad del botón estándar sobre el que se ha hecho clic. Si, en cambio, se ha pulsado Esc, se devuelve el escape button.

El cuadro de mensaje es un cuadro de diálogo de tipo application modal.

Advertencia: No elimines ` parent ` durante la ejecución del cuadro de diálogo. Si deseas hacerlo, debes crear el cuadro de diálogo tú mismo utilizando uno de los constructores de ` QMessageBox `.

Véase también question(), information() y critical().

Documentación de macros

QT_REQUIRE_VERSION(int argc, char **argv, const char *version)

Esta macro se puede utilizar para garantizar que la aplicación se ejecute con una versión de Qt lo suficientemente reciente. Esto resulta especialmente útil si tu aplicación depende de una corrección de errores concreta introducida en una versión de corrección de errores (por ejemplo, la 6.1.2).

Los parámetros « argc » y « argv » corresponden a los parámetros « argc » y « argv » de la función « main() ». El parámetro « version » es una cadena literal que especifica qué versión de Qt requiere la aplicación (por ejemplo, «6.1.2»).

Ejemplo:

#include <QApplication>
#include <QMessageBox>

int main(int argc, char *argv[])
{
    QT_REQUIRE_VERSION(argc, argv, "4.0.2")

    QApplication app(argc, argv);
    //...
    return app.exec();
}

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