ITaskbarList3：：SetProgressValue 方法 (shobjidl_core.h)

项目
08/26/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 以开始显示确定的进度栏，然后根据需要再次调用它，以在进度更改时更新进度条。进度完成后，应用程序必须使用TBPF_NOPROGRESS标志调用 SetProgressState 以消除进度栏。

任务栏按钮如何为组选择进度指示器

任务栏按钮一次只能显示一个窗口的进度指示器。当任务栏按钮表示一个组，并且该组中的多个窗口正在广播进度信息时，任务栏按钮会根据以下状态优先级选择其进度显示。

优先级	状态
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
标头	shobjidl_core.h (包括 Shobjidl.h)
Library	Explorerframe.lib
DLL	Explorerframe.dll