ITaskbarList3::SetProgressState 메서드(shobjidl_core.h)

아티클
08/26/2023

작업 표시줄 단추에 표시되는 진행률 표시기의 유형과 상태를 설정합니다.

구문

HRESULT SetProgressState(
  [in] HWND    hwnd,
  [in] TBPFLAG tbpFlags
);

매개 변수

[in] hwnd

형식: HWND

작업 진행률이 표시되는 창의 핸들입니다. 이 창의 연결된 작업 표시줄 단추에 진행률 표시줄이 표시됩니다.

[in] tbpFlags

형식: TBPFLAG

진행률 단추의 현재 상태를 제어하는 플래그입니다. 다음 플래그 중 하나만 지정합니다. 모든 상태는 다른 모든 주와 상호 배타적입니다.

TBPF_NOPROGRESS(0x00000000)

진행률 표시를 중지하고 단추를 정상 상태로 반환합니다. 작업이 완료되거나 취소될 때 진행률 표시줄을 해제하려면 이 플래그를 사용하여 이 메서드를 호출합니다.

TBPF_INDETERMINATE(0x00000001)

진행률 표시기의 크기는 증가하지 않지만 작업 표시줄 단추의 길이를 따라 반복적으로 순환합니다. 이는 진행률의 완료 비율을 지정하지 않고 활동을 나타냅니다. 진행이 진행 중이지만 작업이 소요되는 기간에 대한 예측은 없습니다.

TBPF_NORMAL(0x00000002)

진행률 표시기의 크기는 완료된 작업의 예상 양에 비례하여 왼쪽에서 오른쪽으로 증가합니다. 이것은 결정적인 진행률 표시기입니다. 작업 기간에 대한 예측이 수행되고 있습니다.

TBPF_ERROR(0x00000004)

진행률 표시기가 빨간색으로 바뀌면 진행률을 브로드캐스트하는 창 중 하나에서 오류가 발생했음을 표시합니다. 이는 결정된 상태입니다. 진행률 표시기가 확정되지 않은 상태이면 실제 진행률을 나타내지 않는 일반 백분율의 빨간색 결정 표시로 전환됩니다.

TBPF_PAUSED(0x00000008)

진행률 표시기가 노란색으로 바뀌면 진행률이 현재 창 중 하나에서 중지되었지만 사용자가 다시 시작할 수 있음을 표시합니다. 오류 조건이 없고 진행이 계속되는 것을 방지하는 조건이 없습니다. 이는 결정된 상태입니다. 진행률 표시기가 확정되지 않은 상태이면 실제 진행률을 나타내지 않는 일반 백분율의 노란색 결정 표시로 전환됩니다.

반환 값

형식: HRESULT

메서드가 성공하면 S_OK를 반환하고, 그러지 않으면 HRESULT 오류 코드를 반환합니다.

설명

접근성 요구 사항이 손상되지 않도록 고대비 색 구성표에는 진행률 표시줄 정보가 표시되지 않습니다.

기존 진행률 표시줄 컨트롤에 익숙한 개발자는 작업 표시줄 단추 진행률 표시기가 개념과 시각적 개체 모두에서 비슷한 환경이어야 합니다. 여기서 작업 표시줄 단추 자체는 진행률 표시줄이 됩니다. 작업 표시줄 단추의 진행률 표시는 연결된 창에서 더 자세한 진행률 표시줄을 반영해야 합니다. 이렇게 하면 작업 표시줄 단추에 표시할 수 없는 백분율 번호 및 남은 시간 등의 세부 정보를 볼 수 있습니다. 또한 작업 표시줄 단추는 그룹에 있는 단일 창의 진행률만 표시할 수 있으므로 사용자가 개별 창의 진행률을 검사 수 있습니다. 또한 고대비 색 구성표와 같이 작업 표시줄 단추를 사용할 수 없는 경우 사용자에게 진행률 정보를 제공합니다.

작업 표시줄 단추 진행률 표시줄은 웹 페이지 로드 또는 문서 인쇄와 같은 일반적으로 주변 작업에 사용할 수 없습니다. 이러한 유형의 진행률은 창의 상태 표시줄에 계속 표시되어야 합니다.

작업 표시줄 단추의 아이콘 또는 텍스트와 배경 사이에 진행률 표시기가 표시됩니다. 활성 작업 표시줄 단추와 비활성 단추 모두에 대해 진행률이 표시되면 해당 진행률 표시줄에서 음영을 지정하면 활성 단추가 사용자에게 계속 표시됩니다. 또한 썸네일 표시와 같은 단추 기능은 진행률을 표시하는 데 단추를 사용할 때 정상적으로 작동합니다.

오류 또는 일시 중지된 상태를 종료할 때 TBPF_NORMAL 또는 TBPF_INDETERMINATE 플래그를 사용하여 이 메서드를 다시 호출하여 원래 상태로 계속 진행하거나 작업이 취소된 경우 TBPF_NOPROGRESS .

작업 표시줄 단추가 그룹의 진행률 표시기를 선택하는 방법

작업 표시줄 단추는 한 번에 하나의 창에 대해서만 진행률 표시기를 표시할 수 있습니다. 여기에는 작업 표시줄 단추가 그룹을 나타내고 해당 그룹의 창이 둘 이상 진행률 정보를 브로드캐스트하는 상황이 포함됩니다. 이 경우 작업 표시줄 단추는 상태 우선 순위에 따라 진행률 표시를 선택합니다. 상태 우선 순위는 다음 표에 나와 있으며 우선 순위 1이 가장 높습니다.

우선 순위	시스템 상태
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

창의 상태를 변경하면 그룹의 다른 창과 관련하여 우선 순위가 변경되어 작업 표시줄 단추의 진행률 표시기에 사용되는 그룹의 창이 변경될 수 있습니다.

확정된 진행률을 브로드캐스트하는 두 창 간에 우선 순위가 충돌하는 경우 진행률이 가장 낮은 창이 사용됩니다.

이 우선 순위에 따라 다음과 같은 경우에만 확정되지 않은 진행률 표시기를 작업 표시줄 단추에 표시할 수 있습니다.

작업 표시줄 단추는 그룹을 나타내지 않으며 그룹을 나타내는 단일 창이 TBPF_INDETERMINATE 설정했습니다.
작업 표시줄 단추는 그룹을 나타내고 해당 그룹의 창 하나만 진행률 정보를 브로드캐스트하고 해당 창은 TBPF_INDETERMINATE 설정했습니다.
작업 표시줄 단추는 그룹을 나타내고, 해당 그룹의 여러 창이 진행률 정보를 브로드캐스트하고, 모든 창이 TBPF_INDETERMINATE 설정했습니다.

다음과 같은 경우 확정된 진행률 표시기를 표시할 수 있습니다.

작업 표시줄 단추는 그룹을 나타내지 않으며 그룹을 나타내는 단일 창은 결정 진행률 정보를 브로드캐스트하는 것입니다.
작업 표시줄 단추는 그룹을 나타내고, 해당 그룹의 창 하나만 진행률 정보를 브로드캐스트하고, 해당 창은 결정된 진행률 정보를 브로드캐스트합니다.
작업 표시줄 단추는 그룹을 나타내고, 해당 그룹의 여러 창이 진행률 정보를 브로드캐스트하고, 해당 창 중 하나 이상이 확정된 진행률 정보를 브로드캐스트하고 있으며, TBPF_ERROR 또는 TBPF_PAUSED 설정된 창이 없습니다.

SetProgressValue를 호출하면 현재 확정되지 않은 모드(TBPF_INDETERMINATE)에 있는 진행률 표시기가 일반(결정) 표시로 전환되고 TBPF_INDETERMINATE 플래그가 지워집니다.

요구 사항


지원되는 최소 클라이언트	Windows 7 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 R2 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	shobjidl_core.h(Shobjidl.h 포함)
라이브러리	Explorerframe.lib
DLL	Explorerframe.dll