ITaskbarList3::SetProgressValue 메서드(shobjidl_core.h)
작업 표시줄 단추에 호스트된 진행률 표시줄을 표시하거나 업데이트하여 전체 작업의 완료된 특정 비율을 표시합니다.
구문
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 |