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

Статья
03/15/2023

Отображает или обновляет индикатор выполнения, размещенный на кнопке панели задач, чтобы отобразить определенный процент завершения полной операции.

Синтаксис

HRESULT SetProgressValue(
  [in] HWND      hwnd,
  [in] ULONGLONG ullCompleted,
  [in] ULONGLONG ullTotal
);

Параметры

[in] hwnd

Тип: HWND

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

[in] ullCompleted

Тип: ULONGLONG

Определенное приложением значение, указывающее долю операции, которая была завершена во время вызова метода.

[in] ullTotal

Тип: ULONGLONG

Определяемое приложением значение, указывающее значение ullCompleted , которое будет иметь после завершения операции.

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

Тип: HRESULT

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

Приложение сначала вызывает SetProgressValue , чтобы начать отображение определенного индикатора выполнения, а затем снова вызывает его при необходимости, чтобы обновить панель по мере изменения хода выполнения. По завершении выполнения приложение должно вызвать SetProgressState с флагом TBPF_NOPROGRESS, чтобы закрыть индикатор выполнения.

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

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

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

Если setProgressState не задал состояние блокировки (TBPF_ERROR или TBPF_PAUSED) для окна, вызов SetProgressValue предполагает состояние TBPF_NORMAL, даже если оно не задано явным образом. Вызов Метода SetProgressValue переопределяет и очищает состояние TBPF_INDETERMINATE.

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

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

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

Если для окна в группе задано TBPF_ERROR или TBPF_PAUSED, это состояние будет использоваться для отображения кнопки. Однако вы по-прежнему можете вызывать SetProgressValue в других разблокированных окнах в группе, чтобы обновить ход выполнения в фоновом режиме.

Примеры

Ниже приведен пример того, как приложение может использовать ITaskbarList3 для отображения хода выполнения операций.

HRESULT CMyApp::ShowProgressInTaskbar(HWND hwnd, __in ITaskbarList3 *pTL)
{
    // Set the progress state of the button to indeterminate while you calculate
    // the number of operations to be performed.
    HRESULT hr = pTL->SetProgressState(hwnd, TBPF_INDETERMINATE);

    // Calculate the number of operations to perform.
    int cTotalOperations = _CalculateNumberOfOperationsToPerform();

    for (int i=0; i < cTotalOperations && SUCCEEDED(hr); i++)
    {
        // Update the progress. This call to SetProgressValue cancels the
        // indeterminate state and puts the button into normal progress mode.
        pTL->SetProgressValue(hwnd, i, cTotalOperations);
       
        // Do whatever operation your application needs to perform.
        hr = _PerformOperation(i);
    }

    // Tell the button that progress no longer needs to be displayed.
    pTL->SetProgressState(hwnd, TBPF_NOPROGRESS);
    
    return hr;
}

Требования

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