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 つのウィンドウについてのみ進行状況インジケーターを表示できます。 タスク バー ボタンがグループを表し、そのグループ内の複数のウィンドウが進行状況情報をブロードキャストしている場合、タスク バー ボタンは次の状態の優先順位に基づいて進行状況の表示を選択します。
優先度 State
1 TBPF_ERROR
2 TBPF_PAUSED
3 TBPF_NORMAL
4 TBPF_INDETERMINATE
 

SetProgressState でウィンドウのブロック状態 (TBPF_ERRORまたはTBPF_PAUSED) が設定されていない限り、SetProgressValue の呼び出しでは、明示的に設定されていない場合でも、TBPF_NORMAL状態が想定されます。 SetProgressValue の呼び出しは、TBPF_INDETERMINATE状態をオーバーライドしてクリアします。

2 つのウィンドウが確定的な進行状況をブロードキャストしている優先度の競合の場合は、進行状況が最も低いウィンドウが使用されます。

この優先度に基づいて、次の場合に、この決定 (特定の割合) の進行状況インジケーターを表示できます。

  • タスク バー ボタンはグループを表せず、それが表す 1 つのウィンドウは、このメソッドを使用して確定的な進行状況情報をブロードキャストしています。
  • タスク バー ボタンはグループを表し、そのグループ内の 1 つのウィンドウだけが進行状況情報をブロードキャストし、そのウィンドウはこのメソッドを使用して確定進行状況情報をブロードキャストしています。
  • タスク バー ボタンはグループを表し、そのグループ内の複数のウィンドウで進行状況情報がブロードキャストされ、少なくとも 1 つのウィンドウがこのメソッドを介して進行状況情報をブロードキャストしており、これらのウィンドウのいずれも 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 を含む)
Library Explorerframe.lib
[DLL] Explorerframe.dll

こちらもご覧ください

ITaskbarList

ITaskbarList2

ITaskbarList3

ITaskbarList3::SetProgressState

タスク バー拡張機能