ITaskbarList3::SetOverlayIcon メソッド (shobjidl_core.h)

  • [アーティクル]

タスク バー ボタンにオーバーレイを適用して、アプリケーションの状態または通知をユーザーに示します。

構文

HRESULT SetOverlayIcon(
  [in] HWND    hwnd,
  [in] HICON   hIcon,
  [in] LPCWSTR pszDescription
);

パラメーター

[in] hwnd

型: HWND

関連付けられたタスク バー ボタンがオーバーレイを受け取るウィンドウのハンドル。 このハンドルは、ボタンのアプリケーションに関連付けられている呼び出しプロセスに属している必要があり、有効な HWND であるか、呼び出しが無視される必要があります。

[in] hIcon

種類: HICON

オーバーレイとして使用するアイコンのハンドル。 これは、96 dpi で 16 x 16 ピクセルを測定する小さなアイコンである必要があります。 タスク バー ボタンにオーバーレイ アイコンが既に適用されている場合は、その既存のオーバーレイが置き換えられます。

この値には NULL を指定できます。 NULL 値の処理方法は、タスク バー ボタンが 1 つのウィンドウを表すか、ウィンドウのグループを表すかによって異なります。

  • タスク バー ボタンが 1 つのウィンドウを表している場合は、オーバーレイ アイコンが表示から削除されます。
  • タスク バー ボタンがウィンドウのグループを表し、以前のオーバーレイが引き続き使用可能な場合 (現在のオーバーレイより前に受け取ったが、 NULL 値で解放されていない場合)、その前のオーバーレイが現在のオーバーレイの代わりに表示されます。

不要になった hIcon を解放するのは、呼び出し元アプリケーションの責任です。 これは、タスク バーがアイコンの独自のコピーを作成して使用するため、 SetOverlayIcon を呼び出した後に一般的に行うことができます。

[in] pszDescription

種類: LPCWSTR

アクセシビリティを目的として、オーバーレイによって伝達される情報の代替テキスト バージョンを提供する文字列へのポインター。

戻り値

型: HRESULT

このメソッドは、成功すると S_OK を返します。 そうでない場合は、HRESULT エラー コードを返します。

注釈

Windows 7 より前のバージョンの Windows では、アプリケーションでは多くの場合、タスク バーの通知領域のアイコンを使用して、アプリケーションの状態と通知をユーザーに表示しました。 Windows 7 タスク バーを使用すると、アプリケーションはタスク バー ボタンを使用して同じ種類のユーザー フィードバックを提供し、アプリケーション情報の多くを 1 か所で一元化できます。 これらのオーバーレイは、ボタンの右下隅に表示されるショートカット アイコンやセキュリティ通知に使用される既存のオーバーレイに似ています。

次の図は、右端のタスク バー ボタンに適用されたオーバーレイ (ユーザーの状態を "使用可能" として示す小さな緑色の四角形) を示しています。

[使用可能] 状態を示すオーバーレイが表示された Windows Messenger タスク バー ボタンのスクリーン ショット アイコン オーバーレイは状態のコンテキスト通知として機能し、その情報をユーザーに伝えるために別の通知領域の状態アイコンの必要性を否定することを目的としています。 アプリケーション デザイナーは、開発サイクル中に、そのアプリケーションに最適な方法 (アイコン オーバーレイまたは通知領域の状態アイコン) を決定する必要があります。 オーバーレイ アイコンは、ネットワークの状態、メッセンジャーの状態、新しいメールなどの重要な、長期的な状態または通知を提供することを目的としています。 頻繁に変更したり、アニメーション化したりしないでください。

オーバーレイ アイコンを表示するには、タスク バーが既定の大きなアイコン モードである必要があります。 タスク バーが タスク バーとスタート メニューのプロパティ を使用して小さなアイコンを表示するように構成されている場合、オーバーレイを適用できず、このメソッドの呼び出しは無視されます。

1 つのオーバーレイが個々のウィンドウのサムネイルではなくタスク バー ボタンに適用されるため、これはウィンドウ単位ではなくグループごとの機能です。 オーバーレイ アイコンの要求は、タスク バー グループ内の個々のウィンドウから受信できますが、キューに入れません。 最後に受け取ったオーバーレイは、表示されるオーバーレイです。 最後に受け取ったオーバーレイが削除された場合、置き換えられたオーバーレイは、アクティブな間は復元されます。 たとえば、ウィンドウ 1、2、3 が順番に設定され、A、B、C がオーバーレイされます。オーバーレイ C は最後に受信されたため、タスク バー ボタンに表示されます。 ウィンドウ 2 は、オーバーレイ B を削除するために NULL 値を持つ SetOverlayIcon を呼び出します。ウィンドウ 3 は、オーバーレイ C を削除するために同じ処理を行います。ウィンドウ 1 のオーバーレイ A はまだアクティブであるため、そのオーバーレイはタスク バー ボタンに表示されます。

Windows エクスプローラーが予期せずシャットダウンした場合、Windows エクスプローラーの復元時にオーバーレイは復元されません。 アプリケーションは、Windows エクスプローラーが再起動され、タスク バー ボタンが再作成されたことを示す TaskbarButtonCreated メッセージの受信を待ってから、SetOverlayIcon をもう一度呼び出してオーバーレイを再適用する必要があります。

要件

要件 値
サポートされている最小のクライアント Windows 7 [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 R2 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー shobjidl_core.h (Shobjidl.h を含む)
Library Explorerframe.lib
[DLL] Explorerframe.dll

こちらもご覧ください

ITaskbarList

ITaskbarList2

ITaskbarList3

タスク バーの拡張機能