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

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

Эта функция была добавлена в 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.

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