ITaskbarList3::SetProgressState メソッド (shobjidl_core.h)
タスク バー ボタンに表示される進行状況インジケーターの種類と状態を設定します。
構文
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 エラー コードを返します。
解説
進行状況バーの情報は、アクセシビリティのニーズが損なわれるのを保証するために、ハイ コントラストの配色では表示されません。
既存の 進行状況バー コントロールに慣れている開発者は、タスク バー ボタンの進行状況インジケーターが、概念とビジュアルの両方で同様のエクスペリエンスである必要があります。 ここで、タスク バー ボタン自体が進行状況バーになります。 タスク バー ボタンの進行状況インジケーターは、関連するウィンドウのより詳細な進行状況バーを反映している必要があります。 これにより、ユーザーは、タスク バー ボタンに表示できない詳細 (パーセンテージ数や残存時間など) を確認できます。 また、タスク バー ボタンはグループ内の 1 つのウィンドウの進行状況のみを表示できるため、ユーザーは個々のウィンドウの進行状況をチェックできます。 また、ハイ コントラストの配色など、タスク バー ボタンができない場合の進行状況情報もユーザーに提供されます。
タスク バー ボタンの進行状況バーは、Web ページの読み込みやドキュメントの印刷など、通常の周辺機器操作では使用できません。 その種類の進行状況は、ウィンドウの ステータス バーに引き続き表示されます。
タスク バー ボタンのアイコンまたはテキストと背景の間に進行状況インジケーターが表示されます。 アクティブなタスク バー ボタンと非アクティブなボタンの両方に進行状況が表示されている場合、それぞれの進行状況バーの網かけは、アクティブなボタンがユーザーにとって明らかになるように表示されます。 また、ボタンが進行状況の表示に使用されている場合、サムネイルの表示などのボタン機能は引き続き正常に動作します。
エラーまたは一時停止状態を終了する場合は、 TBPF_NORMAL または TBPF_INDETERMINATE フラグを指定してこのメソッドを再度呼び出して、元の状態で続行するか、操作が取り消された場合 にTBPF_NOPROGRESS します。
タスク バー ボタンでグループの進行状況インジケーターを選択する方法
タスク バー ボタンには、一度に 1 つのウィンドウについてのみ進行状況インジケーターを表示できます。 これには、タスク バー ボタンがグループを表し、そのグループ内の複数のウィンドウが進行状況情報をブロードキャストしている状況が含まれます。 その場合、タスク バー ボタンは状態の優先度に基づいて進行状況の表示を選択します。 状態の優先度を次の表に示します。優先度 1 が最も高くなっています。| 優先度 | State |
|---|---|
| 1 | TBPF_ERROR |
| 2 | TBPF_PAUSED |
| 3 | TBPF_NORMAL |
| 4 | TBPF_INDETERMINATE |
ウィンドウの状態を変更すると、グループ内の他のウィンドウに対する優先度が変更され、タスク バー ボタンの進行状況インジケーターにグループ内のどのウィンドウが使用されるかが変わる可能性があります。
進行状況をブロードキャストしている 2 つのウィンドウ間で優先度の競合が発生した場合は、進行状況が最も低いウィンドウが使用されます。
この優先度に基づいて、不確定な進行状況インジケーターは、次の場合にのみタスク バー ボタンに表示できます。
- タスク バー ボタンはグループを表せず、それが表す 1 つのウィンドウがTBPF_INDETERMINATE設定されています。
- タスク バー ボタンはグループを表し、そのグループ内の 1 つのウィンドウのみが進行状況情報をブロードキャストしており、そのウィンドウは TBPF_INDETERMINATE設定されています。
- タスク バー ボタンは、グループを表し、そのグループ内の複数のウィンドウが進行状況情報をブロードキャストしており、それらのすべてのウィンドウが TBPF_INDETERMINATE設定されています。
このような場合は、確定進行状況インジケーターを表示できます。
- タスク バー ボタンはグループを表していません。また、それが表す 1 つのウィンドウでは、進行状況を決定する情報がブロードキャストされます。
- タスク バー ボタンはグループを表し、そのグループ内の 1 つのウィンドウだけが進行状況情報をブロードキャストし、そのウィンドウは進行状況情報をブロードキャストしています。
- タスク バー ボタンはグループを表し、そのグループ内の複数のウィンドウが進行状況情報をブロードキャストし、それらのウィンドウの少なくとも 1 つが進行状況情報をブロードキャストしており、 ウィンドウにTBPF_ERROR または TBPF_PAUSEDが設定されていない。
SetProgressValue を呼び出すと、現在不確定モード (TBPF_INDETERMINATE) の進行状況インジケーターが通常の (決定値) 表示に切り替え、TBPF_INDETERMINATE フラグがクリアされることに注意してください。
要件
| サポートされている最小のクライアント | Windows 7 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 R2 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | shobjidl_core.h (Shobjidl.h を含む) |
| Library | Explorerframe.lib |
| [DLL] | Explorerframe.dll |