ITaskbarList3：：SetProgressValue 方法 (shobjidl_core.h)

發行項
03/02/2024

顯示或更新任務列按鈕中裝載的進度列，以顯示完整作業完成的特定百分比。

語法

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 ，才能關閉進度列。

任務欄按鈕如何選擇群組的進度指標

任務列按鈕一次只能顯示一個視窗的進度指示器。當任務欄按鈕代表群組，且該群組中的一個以上的視窗正在廣播進度資訊時，任務欄按鈕會根據下列狀態優先順序選擇其進度顯示。

優先順序	State
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)
程式庫	Explorerframe.lib
Dll	Explorerframe.dll