QDialog Class
La clase QDialog es la clase base de las ventanas de diálogo. Más información...
| Encabezado: | #include <QDialog> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | QWidget |
| Heredado por: | QColorDialog, QErrorMessage, QFileDialog, QFontDialog, QInputDialog, QMessageBox, QProgressDialog y QWizard |
Tipos públicos
| enum | DialogCode { Accepted, Rejected } |
Propiedades
- modal : bool
- sizeGripEnabled : bool
Funciones públicas
| QDialog(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags()) | |
| virtual | ~QDialog() |
| bool | isSizeGripEnabled() const |
| int | result() const |
| void | setModal(bool modal) |
| void | setResult(int i) |
| void | setSizeGripEnabled(bool) |
Funciones públicas reimplementadas
| virtual QSize | minimumSizeHint() const override |
| virtual void | setVisible(bool visible) override |
| virtual QSize | sizeHint() const override |
Ranuras públicas
| virtual void | accept() |
| virtual void | done(int r) |
| virtual int | exec() |
| virtual void | open() |
| virtual void | reject() |
Señales
Funciones protegidas reimplementadas
| virtual void | closeEvent(QCloseEvent *e) override |
| virtual void | contextMenuEvent(QContextMenuEvent *e) override |
| virtual bool | eventFilter(QObject *o, QEvent *e) override |
| virtual void | keyPressEvent(QKeyEvent *e) override |
| virtual void | resizeEvent(QResizeEvent *) override |
| virtual void | showEvent(QShowEvent *event) override |
Descripción detallada
Una ventana de diálogo es una ventana de nivel superior que se utiliza principalmente para tareas de corta duración y comunicaciones breves con el usuario. Los QDialogs pueden ser modales o no modales. Los QDialogs pueden proporcionar un « return value » y pueden tener un « default buttons ». Los QDialogs también pueden tener un « QSizeGrip » en su esquina inferior derecha, utilizando « setSizeGripEnabled()».
Tenga en cuenta que QDialog (y cualquier otro widget que tenga el tipo Qt::Dialog) utiliza el widget padre de forma ligeramente diferente a otras clases de Qt. Un cuadro de diálogo es siempre un widget de nivel superior, pero si tiene un padre, su ubicación por defecto está centrada sobre el widget de nivel superior del padre (si no es él mismo de nivel superior). Además, compartirá la entrada de la barra de tareas del padre.
Utiliza la sobrecarga de la función QWidget::setParent() para cambiar la propiedad de un widget QDialog. Esta función te permite establecer explícitamente los indicadores de ventana del widget al que se le cambia de padre; el uso de la función sobrecargada borrará los indicadores de ventana que especifican las propiedades del sistema de ventanas para el widget (en particular, restablecerá el indicador « Qt::Dialog »).
Nota: La relación de padre-hijo del cuadro de diálogo no implica que este vaya a aparecer siempre encima de la ventana padre. Para garantizar que el cuadro de diálogo esté siempre en primer plano, haz que sea modal. Esto también se aplica a las ventanas hijas del propio cuadro de diálogo. Para garantizar que las ventanas hijas del cuadro de diálogo permanezcan encima de este, haz que también sean modales.
Cuadros de diálogo modales
Un cuadro de diálogo modal es aquel que bloquea la interacción con otras ventanas visibles de la misma aplicación. Los cuadros de diálogo que se utilizan para solicitar al usuario un nombre de archivo o para configurar las preferencias de la aplicación suelen ser modales. Los cuadros de diálogo pueden ser « application modal » (el valor predeterminado) o « window modal ».
Cuando se abre un cuadro de diálogo modal de una aplicación, el usuario debe finalizar su interacción con el cuadro de diálogo y cerrarlo antes de poder acceder a cualquier otra ventana de la aplicación. Los cuadros de diálogo modales de ventana solo bloquean el acceso a la ventana asociada al cuadro de diálogo, lo que permite al usuario seguir utilizando otras ventanas de la aplicación.
La forma más habitual de mostrar un cuadro de diálogo modal es llamar a su función open(). Como alternativa, se puede llamar a setModal(true) o a setWindowModality(), y a continuación a show(). En ambos casos, una vez que se muestra el cuadro de diálogo, el control se devuelve inmediatamente al llamante. Debes conectarte a la señal « finished » () para saber cuándo se cierra el cuadro de diálogo y cuál es su « return value ». Como alternativa, puedes conectarte a las señales « accepted » () y « rejected » ().
Al implementar un cuadro de diálogo personalizado, para cerrarlo y devolver un valor adecuado, conecta un botón predeterminado —por ejemplo, un botón «Aceptar»— a la ranura « accept()», y un botón «Cancelar» a la ranura « reject()». Como alternativa, puedes llamar a la ranura « done()» con « Accepted » o « Rejected ».
Si se muestra el cuadro de diálogo modal para realizar una operación que tarda mucho tiempo, se recomienda ejecutar la operación en un hilo de trabajo en segundo plano, para que no interfiera con el hilo de la interfaz gráfica de usuario.
Advertencia: Al utilizar open() o show(), el cuadro de diálogo modal no debe crearse en la pila, para que no se destruya en cuanto el control vuelva al llamante.
Nota: Existe una forma de mostrar un cuadro de diálogo modal en modo bloqueante llamando a exec(). En este caso, el control vuelve al hilo de la interfaz gráfica de usuario solo cuando se cierra el cuadro de diálogo. Sin embargo, no se recomienda este enfoque, ya que crea un bucle de eventos anidado, que algunas plataformas no admiten por completo.
Cuadros de diálogo no modales
Un cuadro de diálogo no modal es aquel que funciona de forma independiente de otras ventanas de la misma aplicación. Los cuadros de diálogo de «buscar y sustituir» de los procesadores de texto suelen ser no modales para permitir al usuario interactuar tanto con la ventana principal de la aplicación como con el cuadro de diálogo.
Los cuadros de diálogo no modales se muestran mediante la función « show » (), que devuelve el control al llamante de forma inmediata.
Si se invoca la función show() después de ocultar un cuadro de diálogo, este se mostrará en su posición original. Esto se debe a que el gestor de ventanas decide la posición de las ventanas que no han sido colocadas explícitamente por el programador. Para conservar la posición de un cuadro de diálogo que haya sido desplazado por el usuario, guarda su posición en tu controlador ` closeEvent()` y, a continuación, desplaza el cuadro de diálogo a esa posición antes de volver a mostrarlo.
Botón predeterminado
El botón predeterminado de un cuadro de diálogo es aquel que se selecciona cuando el usuario pulsa Intro (Retorno). Este botón se utiliza para indicar que el usuario acepta la configuración del cuadro de diálogo y desea cerrarlo. Utiliza QPushButton::setDefault(), QPushButton::isDefault() y QPushButton::autoDefault() para establecer y controlar el botón predeterminado del cuadro de diálogo.
Tecla Escape
Si el usuario pulsa la tecla Esc en un cuadro de diálogo, se llamará a QDialog::reject(). Esto provocará que la ventana se cierre: close event no puede ser ignored.
Extensibilidad
La extensibilidad es la capacidad de mostrar el cuadro de diálogo de dos formas: un cuadro de diálogo parcial que muestra las opciones más utilizadas y un cuadro de diálogo completo que muestra todas las opciones. Normalmente, un cuadro de diálogo extensible aparecerá inicialmente como un cuadro de diálogo parcial, pero con un botón de alternancia « More ». Si el usuario pulsa el botón « More », el cuadro de diálogo se amplía.
Valor de retorno (cuadros de diálogo modales)
Los cuadros de diálogo modales se utilizan a menudo en situaciones en las que se requiere un valor de retorno, por ejemplo, para indicar si el usuario ha pulsado « OK » o « Cancel ». Un cuadro de diálogo se puede cerrar llamando a las ranuras « accept()» o « reject()», y « exec()» devolverá « Accepted » o « Rejected », según corresponda. La llamada a ` exec()` devuelve el resultado del cuadro de diálogo. El resultado también está disponible mediante ` result()` si el cuadro de diálogo no se ha destruido.
Para modificar el comportamiento de cierre del cuadro de diálogo, puede reimplementar las funciones accept(), reject() o done(). La función closeEvent() solo debe reimplementarse para conservar la posición del cuadro de diálogo o para anular el comportamiento estándar de cierre o rechazo.
Ejemplos de código
Un cuadro de diálogo modal:
void EditorWindow::countWords()
{
WordCountDialog dialog(this);
dialog.setWordCount(document().wordCount());
dialog.exec();
}Un cuadro de diálogo no modal:
void EditorWindow::find()
{
if (!findDialog) {
findDialog = new FindDialog(this);
connect(findDialog, &FindDialog::findNext,
this, &EditorWindow::findNext);
}
findDialog->show();
findDialog->raise();
findDialog->activateWindow();
}Un cuadro de diálogo con una extensión:
mainLayout->setSizeConstraint(QLayout::SetFixedSize);
findButton = new QPushButton(tr("&Find"));
moreButton = new QPushButton(tr("&More..."));
moreButton->setCheckable(true);
extension = new ExtendedControls;
mainLayout->addWidget(extension);
extension->hide();
connect(moreButton, &QAbstractButton::toggled, extension, &QWidget::setVisible);Al establecer la propiedad « sizeConstraint » del diseño del cuadro de diálogo en « SetFixedSize », el usuario no podrá cambiar el tamaño del cuadro de diálogo, y este se reducirá automáticamente cuando se oculte la extensión.
Véase también QDialogButtonBox, QTabWidget, QWidget, QProgressDialog y el ejemplo de cuadros de diálogo estándar.
Documentación sobre los tipos de miembro
enum QDialog::DialogCode
El valor devuelto por un cuadro de diálogo modal.
| Constante | Valor |
|---|---|
QDialog::Accepted | 1 |
QDialog::Rejected | 0 |
Documentación de la propiedad
modal : bool
Esta propiedad determina si la función ` show()` debe mostrar el cuadro de diálogo en modo modal o no modal.
Por defecto, esta propiedad está establecida en « false » y « show()» muestra el cuadro de diálogo como no modal. Establecer esta propiedad en «true» equivale a establecer « QWidget::windowModality » en « Qt::ApplicationModal ».
exec() ignora el valor de esta propiedad y siempre muestra el cuadro de diálogo como modal.
Funciones de acceso:
| bool | isModal() const |
| void | setModal(bool modal) |
Véase también QWidget::windowModality, show() y exec().
sizeGripEnabled : bool
Esta propiedad indica si el controlador de tamaño está activado
Cuando esta propiedad está activada, aparece un control de tamaño ( QSizeGrip ) en la esquina inferior derecha del cuadro de diálogo. Por defecto, el control de tamaño está desactivado.
Funciones de acceso:
| bool | isSizeGripEnabled() const |
| void | setSizeGripEnabled(bool) |
Documentación de las funciones de miembro
[explicit] QDialog::QDialog(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
Crea un cuadro de diálogo cuyo elemento padre es parent.
Un cuadro de diálogo es siempre un widget de nivel superior, pero si tiene un padre, su ubicación predeterminada es centrada en la parte superior del padre. También compartirá la entrada de la barra de tareas del padre.
Los indicadores del widget f se pasan al constructor QWidget. Si, por ejemplo, no quieres que aparezca el botón «¿Qué es esto?» en la barra de título del cuadro de diálogo, pasa Qt::WindowTitleHint | Qt::WindowSystemMenuHint en f.
Véase también QWidget::setWindowFlags().
[virtual noexcept] QDialog::~QDialog()
Elimina el objeto ` QDialog` y borra todos sus elementos secundarios.
[virtual slot] void QDialog::accept()
Oculta el cuadro de diálogo modal y establece el código de resultado en « Accepted ».
Véase también reject() y done().
[signal] void QDialog::accepted()
Esta señal se emite cuando el usuario ha aceptado el cuadro de diálogo o al llamar a ` accept()` o ` done()` con el argumento ` QDialog::Accepted `.
Ten en cuenta que esta señal no se emite al ocultar el cuadro de diálogo con hide() o setVisible(false). Esto incluye la eliminación del cuadro de diálogo mientras está visible.
Véanse también finished() y rejected().
[override virtual protected] void QDialog::closeEvent(QCloseEvent *e)
Reimplementa: ` QWidget::closeEvent(QCloseEvent *event)`.
[override virtual protected] void QDialog::contextMenuEvent(QContextMenuEvent *e)
Reimplementa: QWidget::contextMenuEvent(QContextMenuEvent *event).
[virtual slot] void QDialog::done(int r)
Cierra el cuadro de diálogo y establece su código de resultado en « r ». La señal « finished()» emitirá « r »; si « r » es « QDialog::Accepted » o « QDialog::Rejected », también se emitirán las señales « accepted()» o « rejected()», respectivamente.
Si este cuadro de diálogo se muestra con ` exec()` (), `done()` también provoca que finalice el bucle de eventos local y que ` exec()` devuelva ` r`.
Al igual que con ` QWidget::close()`, `done()` elimina el cuadro de diálogo si está activado el indicador ` Qt::WA_DeleteOnClose `. Si el cuadro de diálogo es el widget principal de la aplicación, esta se cierra. Si el cuadro de diálogo es la última ventana cerrada, se emite la señal ` QGuiApplication::lastWindowClosed()`.
Véanse también accept(), reject(), QApplication::activeWindow() y QCoreApplication::quit().
[override virtual protected] bool QDialog::eventFilter(QObject *o, QEvent *e)
Reimplementa: QObject::eventFilter(QObject *watched, QEvent *event).
[virtual slot] int QDialog::exec()
Muestra el cuadro de diálogo como « modal dialog », bloqueando la aplicación hasta que el usuario lo cierre. La función devuelve un resultado de tipo « DialogCode ».
Si el cuadro de diálogo es « application modal », los usuarios no pueden interactuar con ninguna otra ventana de la misma aplicación hasta que lo cierren. Si el cuadro de diálogo es « window modal », solo se bloquea la interacción con la ventana principal mientras el cuadro de diálogo esté abierto. Por defecto, el cuadro de diálogo es modal para la aplicación.
Nota: Evita utilizar esta función; en su lugar, utiliza ` open()`. A diferencia de `exec()`, ` open()` es asíncrona y no activa un bucle de eventos adicional. Esto evita que se produzcan una serie de errores peligrosos (por ejemplo, eliminar la ventana principal del cuadro de diálogo mientras este está abierto mediante `exec()`). Al utilizar open(), puedes conectarte a la señal finished() de QDialog para recibir una notificación cuando se cierre el cuadro de diálogo.
Véase también open(), show(), result() y setWindowModality().
[signal] void QDialog::finished(int result)
Esta señal se emite cuando se ha establecido el código « result » del cuadro de diálogo, ya sea por parte del usuario o al llamar a las funciones ` done()`, ` accept()` o ` reject()`.
Ten en cuenta que esta señal no se emite al ocultar el cuadro de diálogo con hide() o setVisible(false). Esto incluye la eliminación del cuadro de diálogo mientras está visible.
Véanse también accepted() y rejected().
[override virtual protected] void QDialog::keyPressEvent(QKeyEvent *e)
Reimplementa: ` QWidget::keyPressEvent(QKeyEvent *event)`.
[override virtual] QSize QDialog::minimumSizeHint() const
Reimplementa una función de acceso para la propiedad: QWidget::minimumSizeHint.
[virtual slot] void QDialog::open()
Muestra el cuadro de diálogo como un ` window modal dialog` y devuelve el resultado inmediatamente.
Véase también exec(), show(), result() y setWindowModality().
[virtual slot] void QDialog::reject()
Oculta el cuadro de diálogo modal y establece el código de resultado en « Rejected ».
Véase también accept() y done().
[signal] void QDialog::rejected()
Esta señal se emite cuando el cuadro de diálogo ha sido rechazado, ya sea por el usuario o al llamar a ` reject()` o ` done()` con el argumento ` QDialog::Rejected `.
Ten en cuenta que esta señal no se emite al ocultar el cuadro de diálogo con hide() o setVisible(false). Esto incluye la eliminación del cuadro de diálogo mientras está visible.
Véase también finished() y accepted().
[override virtual protected] void QDialog::resizeEvent(QResizeEvent *)
Reimplementa: QWidget::resizeEvent(QResizeEvent *event).
int QDialog::result() const
En general, devuelve el código de resultado del cuadro de diálogo modal: « Accepted » o « Rejected ».
Nota: Cuando se invoca sobre una instancia de ` QMessageBox `, el valor devuelto es un valor de la enumeración ` QMessageBox::StandardButton `.
No llames a esta función si el cuadro de diálogo se ha creado con el atributo « Qt::WA_DeleteOnClose ».
Véase también setResult().
void QDialog::setResult(int i)
Establece el código de resultado del cuadro de diálogo modal en « i ».
Nota: Se recomienda utilizar uno de los valores definidos en QDialog::DialogCode.
Véase también ` result()`.
[override virtual] void QDialog::setVisible(bool visible)
Reimplementa una función de acceso para la propiedad: QWidget::visible.
[override virtual protected] void QDialog::showEvent(QShowEvent *event)
Reimplementa: ` QWidget::showEvent(QShowEvent *event)`.
[override virtual] QSize QDialog::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.