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

タスク バーの拡張機能