Класс 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 — родительский виджет диалога. Родительский виджет и флаги виджета 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.

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