Метод ITaskbarList3::SetProgressState (shobjidl_core.h)

Статья
08/26/2023

Задает тип и состояние индикатора хода выполнения, отображаемого на кнопке панели задач.

Синтаксис

HRESULT SetProgressState(
  [in] HWND    hwnd,
  [in] TBPFLAG tbpFlags
);

Параметры

[in] hwnd

Тип: HWND

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

[in] tbpFlags

Тип: TBPFLAG

Флаги, управляющие текущим состоянием кнопки хода выполнения. Укажите только один из следующих флагов: все состояния являются взаимоисключающими из всех остальных.

TBPF_NOPROGRESS (0x00000000)

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

TBPF_INDETERMINATE (0x00000001)

Индикатор хода выполнения не увеличивается в размере, а циклически выполняется по длине кнопки панели задач. Это указывает на действие, не указывая, какая доля хода выполнения завершена. Ход выполнения выполняется, но нет прогноза о том, сколько времени займет операция.

TBPF_NORMAL (0x00000002)

Индикатор хода выполнения увеличивается слева направо пропорционально предполагаемому объему завершенной операции. Это определенный индикатор хода выполнения; выполняется прогноз продолжительности операции.

TBPF_ERROR (0x00000004)

Индикатор хода выполнения становится красным, чтобы показать, что в одном из окон, транслирующих ход выполнения, произошла ошибка. Это определенное состояние. Если индикатор хода выполнения находится в неопределенном состоянии, он переключается на красный определенный индикатор общего процента, не указывающий на фактический ход выполнения.

TBPF_PAUSED (0x00000008)

Индикатор хода выполнения становится желтым, чтобы показать, что ход выполнения в настоящее время остановлен в одном из окон, но может быть возобновлен пользователем. Условие ошибки не существует, и ничто не препятствует продолжению хода выполнения. Это определенное состояние. Если индикатор хода выполнения находится в неопределенном состоянии, он переключается на желтый определенный индикатор общего процента, не указывающий на фактический ход выполнения.

Возвращаемое значение

Тип: HRESULT

Если этот метод завершается успешно, он возвращает S_OK. В противном случае возвращается код ошибки HRESULT .

Сведения о индикаторе выполнения не отображаются в высококонтрастных цветовых схемах, чтобы гарантировать, что требования к специальным возможностям не будут скомпрометированы.

Разработчики, привыкшие к существующему элементу управления индикатором выполнения , должны найти индикатор хода выполнения кнопки на панели задач, чтобы он был похожим как в концепции, так и в визуальных элементах. Здесь сама кнопка панели задач становится индикатором выполнения. Индикатор хода выполнения кнопки панели задач должен быть отражением более подробного индикатора выполнения в соответствующем окне. Это позволяет пользователю видеть особенности, такие как процентное число и оставшееся время, которые не могут отображаться на кнопке панели задач. Кроме того, поскольку кнопка панели задач может отображать ход выполнения только одного окна в группе, она позволяет пользователю проверка ход выполнения отдельных окон. Он также предоставляет пользователю сведения о ходе выполнения, когда кнопка панели задач не может, например в цветовой схеме с высокой контрастностью.

Обратите внимание, что индикатор выполнения кнопки панели задач не предназначен для использования с обычными периферийными действиями, такими как загрузка веб-страницы или печать документа. Этот тип хода выполнения должен по-прежнему отображаться в строке состояния окна.

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

При выходе из состояния ошибки или приостановки вызовите этот метод еще раз с флагом TBPF_NORMAL или TBPF_INDETERMINATE , чтобы продолжить работу в исходном состоянии или TBPF_NOPROGRESS , если операция отменена.

Выбор индикатора хода выполнения для группы кнопкой панели задач

Кнопка панели задач может отображать индикатор хода выполнения только для одного окна за раз. Это относится к ситуации, когда кнопка панели задач представляет группу и несколько окон в ней транслируют сведения о ходе выполнения. В этом случае кнопка панели задач выбирает отображение хода выполнения в зависимости от приоритета состояния. Приоритет состояния показан в следующей таблице, а приоритет 1 — самый высокий.

Приоритет	Состояние
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

Изменение состояния окна изменяет приоритет по отношению к другим окнам в группе, что, в свою очередь, может изменить окно в группе, используемое для индикатора хода выполнения на кнопке панели задач.

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

В зависимости от этого приоритета индикатор неопределенного хода выполнения может отображаться на кнопке панели задач только в следующих случаях:

Кнопка панели задач не представляет группу, а одно окно, которое она представляет, имеет TBPF_INDETERMINATE.
Кнопка панели задач представляет группу, только одно окно в ней транслирует сведения о ходе выполнения, и в этом окне задано TBPF_INDETERMINATE.
Кнопка панели задач представляет группу, несколько окон в ней транслируют сведения о ходе выполнения, и для всех этих окон задано TBPF_INDETERMINATE.

Индикатор хода выполнения может отображаться в следующих случаях:

Кнопка панели задач не представляет группу, а одно окно, которое она представляет, является трансляцией определенных сведений о ходе выполнения.
Кнопка панели задач представляет группу, только одно окно в ней транслирует сведения о ходе выполнения, а это окно транслирует определенные сведения о ходе выполнения.
Кнопка панели задач представляет группу, несколько окон в ней транслируют сведения о ходе выполнения, по крайней мере одно из них транслирует определенные сведения о ходе выполнения, и ни в одном окне не задано TBPF_ERROR или TBPF_PAUSED.

Обратите внимание, что вызов SetProgressValue переключит индикатор хода выполнения, который в настоящее время находится в неопределенном режиме (TBPF_INDETERMINATE), на обычный (определенный) дисплей и снимет флаг TBPF_INDETERMINATE .

Требования


Минимальная версия клиента	Windows 7 [только классические приложения]
Минимальная версия сервера	Windows Server 2008 R2 [только классические приложения]
Целевая платформа	Windows
Header	shobjidl_core.h (включая Shobjidl.h)
Библиотека	Explorerframe.lib
DLL	Explorerframe.dll