QProgressDialog Class
La clase QProgressDialog muestra información sobre el progreso de una operación lenta. Más información...
| Encabezado: | #include <QProgressDialog> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | QDialog |
- Lista de todos los miembros, incluidos los heredados
- QProgressDialog forma parte de Diálogos estándar.
Propiedades
|
Funciones públicas
| QProgressDialog(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags()) | |
| QProgressDialog(const QString &labelText, const QString &cancelButtonText, int minimum, int maximum, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags()) | |
| virtual | ~QProgressDialog() |
| bool | autoClose() const |
| bool | autoReset() const |
| QString | labelText() const |
| int | maximum() const |
| int | minimum() const |
| int | minimumDuration() const |
| void | open(QObject *receiver, const char *member) |
| void | setAutoClose(bool close) |
| void | setAutoReset(bool reset) |
| void | setBar(QProgressBar *bar) |
| void | setCancelButton(QPushButton *cancelButton) |
| void | setLabel(QLabel *label) |
| int | value() const |
| bool | wasCanceled() const |
Funciones públicas reimplementadas
| virtual QSize | sizeHint() const override |
Ranuras públicas
| void | cancel() |
| void | reset() |
| void | setCancelButtonText(const QString &cancelButtonText) |
| void | setLabelText(const QString &text) |
| void | setMaximum(int maximum) |
| void | setMinimum(int minimum) |
| void | setMinimumDuration(int ms) |
| void | setRange(int minimum, int maximum) |
| void | setValue(int progress) |
Señales
| void | canceled() |
Funciones protegidas reimplementadas
| virtual void | changeEvent(QEvent *ev) override |
| virtual void | closeEvent(QCloseEvent *e) override |
| virtual void | resizeEvent(QResizeEvent *event) override |
| virtual void | showEvent(QShowEvent *e) override |
Ranuras protegidas
| void | forceShow() |
Descripción detallada
Un cuadro de diálogo de progreso se utiliza para indicar al usuario cuánto tiempo va a tardar una operación y para demostrar que la aplicación no se ha bloqueado. También puede ofrecer al usuario la oportunidad de cancelar la operación.
Un problema habitual con los cuadros de diálogo de progreso es que resulta difícil saber cuándo utilizarlos, ya que las operaciones tardan más o menos tiempo según el hardware. QProgressDialog ofrece una solución a este problema: calcula el tiempo que tardará la operación (basándose en el tiempo de cada paso) y solo se muestra si ese tiempo estimado supera el valor de minimumDuration() (4 segundos por defecto).
Utiliza setMinimum() y setMaximum() o el constructor para establecer el número de «pasos» de la operación y llama a setValue() a medida que avanza la operación. El número de pasos se puede elegir de forma arbitraria. Puede ser el número de archivos copiados, el número de bytes recibidos, el número de iteraciones a través del bucle principal de tu algoritmo o cualquier otra unidad adecuada. El progreso comienza con el valor establecido por setMinimum(), y el cuadro de diálogo de progreso muestra que la operación ha finalizado cuando se llama a setValue() con el valor establecido por setMaximum() como argumento.
El cuadro de diálogo se restablece automáticamente y se oculta al finalizar la operación. Utiliza setAutoReset() y setAutoClose() para modificar este comportamiento. Ten en cuenta que si estableces un nuevo valor máximo (utilizando setMaximum() o setRange()) que sea igual a tu value() actual, el cuadro de diálogo no se cerrará en ningún caso.
Hay dos formas de utilizar QProgressDialog: modal y no modal.
En comparación con un QProgressDialog no modal, un QProgressDialog modal resulta más sencillo de usar para el programador. Realiza la operación en un bucle, llama a setValue() a intervalos regulares y comprueba si se ha cancelado con wasCanceled(). Por ejemplo:
QProgressDialog progress("Copying files...", "Abort Copy", 0, numFiles, this);
progress.setWindowModality(Qt::WindowModal);
for (int i = 0; i < numFiles; i++) {
progress.setValue(i);
if (progress.wasCanceled())
break;
//... copy one file
}
progress.setValue(numFiles);Un cuadro de diálogo de progreso no modal es adecuado para operaciones que tienen lugar en segundo plano, en las que el usuario puede interactuar con la aplicación. Estas operaciones suelen basarse en una clase de temporizador, como ` QChronoTimer ` (o la función de nivel más bajo ` QObject::timerEvent()`) o ` QSocketNotifier`; o bien se ejecutan en un hilo independiente. Un indicador de progreso ( QProgressBar ) en la barra de estado de la ventana principal suele ser una alternativa a un cuadro de diálogo de progreso no modal.
Es necesario tener un bucle de eventos en ejecución, conectar la señal canceled() a un slot que detenga la operación y llamar a setValue() a intervalos regulares. Por ejemplo:
// Operation constructor
Operation::Operation(QObject *parent)
: QObject(parent), steps(0)
{
pd = new QProgressDialog("Operation in progress.", "Cancel", 0, 100);
connect(pd, &QProgressDialog::canceled, this, &Operation::cancel);
t = new QTimer(this);
connect(t, &QTimer::timeout, this, &Operation::perform);
t->start(0);
}
void Operation::perform()
{
pd->setValue(steps);
//... perform one percent of the operation
steps++;
if (steps > pd->maximum())
t->stop();
}
void Operation::cancel()
{
t->stop();
//... cleanup
}En ambos modos, el cuadro de diálogo de progreso se puede personalizar sustituyendo los widgets secundarios por widgets personalizados mediante setLabel(), setBar() y setCancelButton(). Las funciones setLabelText() y setCancelButtonText() establecen los textos que se muestran.

Véase también QDialog y QProgressBar.
Documentación de propiedades
autoClose : bool
Esta propiedad indica si el cuadro de diálogo queda oculto al llamar a reset()
El valor predeterminado es «true».
Funciones de acceso:
| bool | autoClose() const |
| void | setAutoClose(bool close) |
Véase también ` setAutoReset()`.
autoReset : bool
Esta propiedad indica si el cuadro de diálogo de progreso llama a ` reset()` en cuanto ` value()` sea igual a ` maximum()`.
El valor predeterminado es «true».
Funciones de acceso:
| bool | autoReset() const |
| void | setAutoReset(bool reset) |
Véase también setAutoClose().
labelText : QString
Esta propiedad contiene el texto de la etiqueta
El texto por defecto es una cadena vacía.
Funciones de acceso:
| QString | labelText() const |
| void | setLabelText(const QString &text) |
maximum : int
Esta propiedad contiene el valor máximo que representa la barra de progreso
El valor por defecto es 100.
Funciones de acceso:
| int | maximum() const |
| void | setMaximum(int maximum) |
Véase también minimum y setRange().
minimum : int
Esta propiedad contiene el valor más bajo representado por la barra de progreso
El valor por defecto es 0.
Funciones de acceso:
| int | minimum() const |
| void | setMinimum(int minimum) |
Véase también maximum y setRange().
minimumDuration : int
Esta propiedad indica el tiempo que debe transcurrir antes de que aparezca el cuadro de diálogo
Si la duración prevista de la tarea es inferior a «minimumDuration», el cuadro de diálogo no aparecerá en absoluto. Esto evita que el cuadro de diálogo se muestre en tareas que finalizan rápidamente. En el caso de las tareas que se prevé que superen «minimumDuration», el cuadro de diálogo aparecerá una vez transcurrido el tiempo «minimumDuration» o tan pronto como se registre algún progreso.
Si se establece en 0, el cuadro de diálogo siempre se muestra tan pronto como se registre algún progreso. El valor predeterminado es 4000 milisegundos.
Funciones de Access:
| int | minimumDuration() const |
| void | setMinimumDuration(int ms) |
value : int
Esta propiedad contiene el valor actual del progreso alcanzado.
Para que el cuadro de diálogo de progreso funcione como se espera, debes establecer inicialmente esta propiedad en QProgressDialog::minimum() y, finalmente, en QProgressDialog::maximum(); puedes llamar a setValue() tantas veces como quieras entre medias.
Advertencia: Si el cuadro de diálogo de progreso es modal (véase QProgressDialog::QProgressDialog()), setValue() llama a QCoreApplication::processEvents(), por lo que hay que tener cuidado de que esto no provoque una reentrada indeseada en el código. Por ejemplo, no utilices un QProgressDialog dentro de un paintEvent()!
Funciones de acceso:
| int | value() const |
| void | setValue(int progress) |
Véase también minimum y maximum.
[read-only] wasCanceled : bool
Esta propiedad indica si se ha cancelado el cuadro de diálogo
Funciones de Access:
| bool | wasCanceled() const |
Documentación de las funciones de miembro
[explicit] QProgressDialog::QProgressDialog(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
Crea un cuadro de diálogo de progreso.
Configuración predeterminada:
- El texto de la etiqueta está vacío.
- El texto del botón «Cancelar» es (traducido) «Cancelar».
- El valor mínimo es 0;
- el máximo es 100
El argumento ` parent ` es el widget padre del cuadro de diálogo. Los indicadores del widget, ` f`, se pasan al constructor ` QDialog::QDialog()`.
Véase también setLabelText(), setCancelButtonText(), setCancelButton(), setMinimum() y setMaximum().
QProgressDialog::QProgressDialog(const QString &labelText, const QString &cancelButtonText, int minimum, int maximum, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
Crea un cuadro de diálogo de progreso.
El ` labelText ` es el texto que se utiliza para indicar al usuario en qué proceso se encuentra la operación.
cancelButtonText es el texto que se muestra en el botón de cancelación. Si se pasa QString(), no se muestra ningún botón de cancelación.
minimum y maximum son el número de pasos de la operación para la que este cuadro de diálogo de progreso muestra el avance. Por ejemplo, si la operación consiste en examinar 50 archivos, el valor mínimo sería 0 y el máximo, 50. Antes de examinar el primer archivo, llama a setValue(0). A medida que se procesa cada archivo, llama a setValue(0), setValue(2), etc., y finalmente llama a setValue(50) tras examinar el último archivo.
El argumento parent es el widget padre del cuadro de diálogo. El padre, parent, y los indicadores del widget, f, se pasan al constructor QDialog::QDialog().
Véanse también setLabelText(), setLabel(), setCancelButtonText(), setCancelButton(), setMinimum() y setMaximum().
[virtual noexcept] QProgressDialog::~QProgressDialog()
Cierra el cuadro de diálogo de progreso.
[slot] void QProgressDialog::cancel()
Restablece el cuadro de diálogo de progreso. La propiedad ` wasCanceled()` pasa a ser `true` hasta que se restablezca el cuadro de diálogo de progreso. El cuadro de diálogo de progreso se oculta.
[signal] void QProgressDialog::canceled()
Esta señal se emite al hacer clic en el botón «Cancelar». De forma predeterminada, está conectada a la ranura cancel().
Véase también wasCanceled().
[override virtual protected] void QProgressDialog::changeEvent(QEvent *ev)
Reimplementa: ` QWidget::changeEvent(QEvent *event)`.
[override virtual protected] void QProgressDialog::closeEvent(QCloseEvent *e)
Reimplementa: ` QDialog::closeEvent(QCloseEvent *e)`.
[protected slot] void QProgressDialog::forceShow()
Muestra el cuadro de diálogo si sigue oculto después de que se haya iniciado el algoritmo y hayan transcurrido minimumDuration milisegundos.
Véase también setMinimumDuration().
void QProgressDialog::open(QObject *receiver, const char *member)
Abre el cuadro de diálogo y conecta su señal « canceled()» a las ranuras especificadas por « receiver » y « member ».
La señal se desconectará de la ranura cuando se cierre el cuadro de diálogo.
[slot] void QProgressDialog::reset()
Restablece el cuadro de diálogo de progreso. El cuadro de diálogo de progreso queda oculto si autoClose() es verdadero.
Véase también setAutoClose() y setAutoReset().
[override virtual protected] void QProgressDialog::resizeEvent(QResizeEvent *event)
Reimplementa: ` QDialog::resizeEvent` (`QResizeEvent *)`.
void QProgressDialog::setBar(QProgressBar *bar)
Establece el control de barra de progreso en ` bar`. El cuadro de diálogo de progreso se redimensiona para ajustarse al espacio. El cuadro de diálogo de progreso asume la propiedad del objeto de progreso ` bar `, que se eliminará cuando sea necesario; por lo tanto, no utilices una barra de progreso asignada en la pila.
void QProgressDialog::setCancelButton(QPushButton *cancelButton)
Establece el botón de cancelación en el botón pulsador cancelButton. El cuadro de diálogo de progreso toma el control de este botón, que se eliminará cuando sea necesario, por lo que no debes pasar la dirección de un objeto que se encuentre en la pila; es decir, utiliza new() para crear el botón. Si se pasa nullptr, no se mostrará ningún botón de cancelación.
Véase también setCancelButtonText().
[slot] void QProgressDialog::setCancelButtonText(const QString &cancelButtonText)
Establece el texto del botón «Cancelar» como « cancelButtonText ». Si el texto se establece como QString(), el botón «Cancelar» se ocultará y se eliminará.
Véase también ` setCancelButton()`.
void QProgressDialog::setLabel(QLabel *label)
Establece la etiqueta en « label ». El cuadro de diálogo de progreso cambia de tamaño para adaptarse a ella. La etiqueta pasa a ser propiedad del cuadro de diálogo de progreso y se eliminará cuando sea necesario, por lo que no se debe pasar la dirección de un objeto que se encuentre en la pila.
Véase también setLabelText().
[slot] void QProgressDialog::setRange(int minimum, int maximum)
Establece los valores mínimo y máximo del cuadro de diálogo de progreso en minimum y maximum, respectivamente.
Si maximum es menor que minimum, minimum se convierte en el único valor válido.
Si el valor actual queda fuera del nuevo rango, el cuadro de diálogo de progreso se restablece con reset().
Véase también minimum y maximum.
[override virtual protected] void QProgressDialog::showEvent(QShowEvent *e)
Reimplementa: ` QDialog::showEvent(QShowEvent *event)`.
[override virtual] QSize QProgressDialog::sizeHint() const
Reimplementa: ` QDialog::sizeHint()` const.
Devuelve un tamaño que se adapta al contenido del cuadro de diálogo de progreso. El cuadro de diálogo de progreso se redimensiona automáticamente según sea necesario, por lo que no debería ser necesario que lo llames tú mismo.
© 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.