ITaskbarList3::SetProgressValue method (shobjidl_core.h)

Article
10/13/2021

Displays or updates a progress bar hosted in a taskbar button to show the specific percentage completed of the full operation.

Syntax

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

Parameters

[in] hwnd

Type: HWND

The handle of the window whose associated taskbar button is being used as a progress indicator.

[in] ullCompleted

Type: ULONGLONG

An application-defined value that indicates the proportion of the operation that has been completed at the time the method is called.

[in] ullTotal

Type: ULONGLONG

An application-defined value that specifies the value ullCompleted will have when the operation is complete.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Determinate Progress Bar Lifecycle

An application first calls SetProgressValue to begin the display of a determinate progress bar, and then calls it again as needed to update the bar as the progress changes. When progress is complete, the application must call SetProgressState with the TBPF_NOPROGRESS flag to dismiss the progress bar.

How the Taskbar Button Chooses the Progress Indicator for a Group

The taskbar button can show a progress indicator for only one window at a time. When the taskbar button represents a group and more than one of the windows in that group are broadcasting progress information, the taskbar button chooses its progress display based on the following state priority.

Priority	State
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

Unless SetProgressState has set a blocking state (TBPF_ERROR or TBPF_PAUSED) for the window, a call to SetProgressValue assumes the TBPF_NORMAL state even if it is not explicitly set. A call to SetProgressValue overrides and clears the TBPF_INDETERMINATE state.

In the case of a priority collision where two windows are broadcasting determinate progress, the window with the least progress is used.

Based on that priority, this determinate (specific percentage) progress indicator can be displayed in these cases:

The taskbar button does not represent a group and the single window that it represents is broadcasting determinate progress information through this method.
The taskbar button represents a group, only one window in that group is broadcasting progress information, and that window is broadcasting determinate progress information through this method.
The taskbar button represents a group, multiple windows in that group are broadcasting progress information, at least one of those windows is broadcasting progress information through this method, and none of those windows has set the TBPF_ERROR or TBPF_PAUSED state.

If a window in the group has set TBPF_ERROR or TBPF_PAUSED, that state will be used for the button display. However, you can still make calls to SetProgressValue on other, unblocked windows in the group to update their progress in the background.

Examples

Here is an example of how an application could use ITaskbarList3 to display progress while it is performing operations.

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;
}

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Target Platform	Windows
Header	shobjidl_core.h (include Shobjidl.h)
Library	Explorerframe.lib
DLL	Explorerframe.dll