Класс 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 файлов, минимальное значение будет 0, а максимальное — 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.

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