Класс 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.

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