Класс QProgressDialog

Класс QProgressDialog предоставляет обратную связь о ходе выполнения медленной операции. Подробнее...

• Список всех членов, включая унаследованные

Свойства

Открытые функции

Переопределённые открытые функции

Открытые слоты

Сигналы

Переопределённые защищённые функции

Защищённые слоты

Подробное описание

Диалог прогресса используется для отображения пользователю, сколько времени займет выполнение операции, и для демонстрации того, что приложение не зависло. Он также может предоставить пользователю возможность прервать операцию.

Общая проблема с диалогами прогресса заключается в том, как определить, когда их следует использовать; операции занимают разное время на разных аппаратных платформах. QProgressDialog предлагает решение этой проблемы: он оценивает время, необходимое для выполнения операции (на основе времени для шагов), и отображает себя только в том случае, если эта оценка превышает minimumDuration() (по умолчанию 4 секунды).

Используйте setMinimum() и setMaximum() или конструктор для установки количества «шагов» в операции и вызывайте setValue() по мере выполнения операции. Количество шагов можно выбрать произвольно. Это может быть количество скопированных файлов, количество полученных байтов, количество итераций по основному циклу вашего алгоритма или другая подходящая единица измерения. Прогресс начинается со значения, установленного с помощью setMinimum(), и диалог прогресса показывает, что операция завершена, когда вы вызываете setValue() со значением, установленным с помощью setMaximum(), в качестве аргумента.

Диалог автоматически сбрасывается и скрывается в конце операции. Используйте setAutoReset() и setAutoClose(), чтобы изменить это поведение. Обратите внимание, что если вы установите новое максимальное значение (с помощью setMaximum() или setRange()), равное текущему значению value(), диалог не закроется.

Существует два способа использования QProgressDialog: модальный и безымянный.

По сравнению с безымянным QProgressDialog, модальный QProgressDialog проще в использовании для программиста. Выполняйте операцию в цикле, вызывайте setValue() с интервалами и проверяйте на отмену с помощью wasCanceled(). Например:

    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);

Безымянный диалог прогресса подходит для операций, которые выполняются в фоновом режиме, где пользователь может взаимодействовать с приложением. Такие операции обычно основаны на QTimer (или QObject::timerEvent()) или QSocketNotifier; или выполняются в отдельном потоке. QProgressBar в строке состояния вашего главного окна часто является альтернативой безымянному диалогу прогресса.

Для работы необходимо, чтобы был запущен цикл событий, подключить сигнал canceled() к слоту, который останавливает операцию, и вызывать setValue() через определенные промежутки времени. Например:

// 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
}

В обоих режимах диалог прогресса можно настроить, заменив дочерние виджеты пользовательскими виджетами, используя setLabel(), setBar() и setCancelButton(). Функции setLabelText() и setCancelButtonText() устанавливают текст, отображаемый в диалоге.

См. также QDialog, QProgressBar, Руководство по проектированию пользовательского интерфейса: индикатор прогресса, Пример поиска файлов и Пример Pixelator.

Документация членов-функций

QProgressDialog::QProgressDialog(const QString &labelText, const QString &cancelButtonText, int minimum, int maximum, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

Конструирует диалог прогресса.

labelText — текст, используемый для напоминания пользователю о процессе.

cancelButtonText — текст для отображения на кнопке отмены. Если передан QString(), кнопка отмены не отображается.

minimum и maximum — количество шагов в операции, для которой этот диалог прогресса отображает прогресс. Например, если операция состоит в просмотре 50 файлов, значение minimum будет 0, а maximum — 50. Перед просмотром первого файла вызовите setValue(0). При обработке каждого файла вызывайте setValue(1), setValue(2) и т. д., наконец, вызвав setValue(50) после просмотра последнего файла.

Аргумент parent — родительский виджет диалога. Родительский виджет, parent, и флаги виджета, f, передаются в конструктор QDialog::QDialog().

См. также setLabelText(), setLabel(), setCancelButtonText(), setCancelButton(), setMinimum() и setMaximum().

QProgressDialog::QProgressDialog(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

Конструирует диалог прогресса.

Значения по умолчанию:

• Текст метки — пустой.
• Текст кнопки отмены — (переведённый) "Отмена".
• minimum — 0;
• maximum — 100

Аргумент parent — родительский виджет диалога. Флаги виджета, f, передаются в конструктор QDialog::QDialog().

См. также setLabelText(), setCancelButtonText(), setCancelButton(), setMinimum() и setMaximum().

[slot] void QProgressDialog::cancel()

Сбрасывает диалог прогресса. wasCanceled() становится true до тех пор, пока диалог прогресса не будет сброшен. Диалог прогресса скрывается.

[signal] void QProgressDialog::canceled()

Этот сигнал испускается при нажатии на кнопку отмены. По умолчанию он подключается к слоту cancel().

См. также wasCanceled().

[protected slot] void QProgressDialog::forceShow()

Отображает диалог, если он по-прежнему скрыт после запуска алгоритма и прошло minimumDuration миллисекунд.

См. также setMinimumDuration().

[slot] void QProgressDialog::reset()

Сбрасывает диалог прогресса. Диалог прогресса скрывается, если autoClose() имеет значение true.

См. также setAutoClose() и setAutoReset().

[slot] void QProgressDialog::setCancelButtonText(const QString &cancelButtonText)

Устанавливает текст кнопки отмены на cancelButtonText. Если текст установлен на QString(), кнопка отмены будет скрыта и удалена.

См. также setCancelButton().

[slot] void QProgressDialog::setRange(int minimum, int maximum)

Устанавливает минимальное и максимальное значения диалога прогресса на minimum и maximum соответственно.

Если maximum меньше minimum, minimum становится единственным допустимым значением.

Если текущее значение выходит за пределы нового диапазона, диалог прогресса сбрасывается с помощью reset().

См. также minimum и maximum.

[virtual] QProgressDialog::~QProgressDialog()

Уничтожает диалог прогресса.

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

Переопределяет: QWidget::changeEvent(QEvent *event).

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

Переопределяет: QDialog::closeEvent(QCloseEvent *e).

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

Открывает диалог и подключает его сигнал canceled() к слоту, указанному receiver и member.

Сигнал будет отключен от слота, когда диалог будет закрыт.

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

Переопределяет: QDialog::resizeEvent(QResizeEvent *).

void QProgressDialog::setBar(QProgressBar *bar)

Устанавливает виджет полосы прогресса на bar. Диалог прогресса перенастраивает свой размер для соответствия. Диалог прогресса принимает владение полосой прогресса bar, которая будет удалена при необходимости, поэтому не используйте полосу прогресса, выделенную в стеке.

void QProgressDialog::setCancelButton(QPushButton *cancelButton)

Устанавливает кнопку отмены на кнопку cancelButton. Диалог прогресса принимает владение этой кнопкой, которая будет удалена при необходимости, поэтому не передавайте адрес объекта, находящегося в стеке, т.е. используйте new() для создания кнопки. Если nullptr передано, кнопка отмены не будет отображаться.

См. также setCancelButtonText().

void QProgressDialog::setLabel(QLabel *label)

Устанавливает метку на label. Диалог прогресса перенастраивает свой размер для соответствия. Метка переходит во владение диалога прогресса и будет удалена при необходимости, поэтому не передавайте адрес объекта, находящегося в стеке.

См. также setLabelText().

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

Переопределяет: QDialog::showEvent(QShowEvent *event).

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

Переопределяет: QDialog::sizeHint() const.

Возвращает размер, подходящий для содержимого диалога прогресса. Диалог прогресса перенастраивает свой размер при необходимости, поэтому вам не нужно вызывать эту функцию самостоятельно.