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 포함)
라이브러리	Explorerframe.lib
DLL	Explorerframe.dll