Класс 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, Руководство по проектированию пользовательского интерфейса: Индикатор выполнения, Пример Find Files и Пример 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.

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

Эта функция была добавлена в Qt 4.5.

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

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