IShellIconOverlay

名前空間拡張が、それに含まれるオブジェクトのアイコンオーバーレイを指定するために使用するメソッドを公開します。

アイコンオーバーレイは、Shell オブジェクトを表すアイコンの左下隅に配置される小さな画像です。通常、アイコンに何らかの追加情報を付加するために使用されます。よく使われるアイコンオーバーレイの例として、ファイルやフォルダーのアイコンがショートカットを表していることを示す小さな矢印があります。

アイコンオーバーレイはシステムイメージリストの一部です。これらには 2 つの識別子があります。1 つは、イメージリスト内の他のオーバーレイに対する相対的なオーバーレイを識別する、1 から始まるオーバーレイインデックスです。もう 1 つは、実際の画像を識別するイメージインデックスです。これら 2 つのインデックスは、ImageList::SetOverlayImage でプライベートイメージリストにアイコンオーバーレイを追加する際に、それぞれ iOverlay パラメーターと iImage パラメーターに割り当てる値と同等です。

オブジェクトのアイコンを表示する前に、Shell は関連付けられたフォルダーの IShellIconOverlay インターフェイスを呼び出して、そのオブジェクトのアイコンにオーバーレイを付けるべきかどうかを照会します。通常は IShellIconOverlay::GetOverlayIndex を呼び出して、オーバーレイのオーバーレイインデックスを要求します。場合によっては、Shell が IShellIconOverlay::GetOverlayIconIndex を呼び出して、オーバーレイのイメージインデックスを要求することもあります。アイコンオーバーレイを指定するには、これらのメソッドは要求されたインデックスを返す必要があります。それ以外の場合は S_FALSE を返します。

アイコンオーバーレイを指定するには、両方のメソッドともまず SHGetIconOverlayIndex を呼び出して、システムイメージリスト内のオーバーレイのオーバーレイインデックスを取得する必要があります。SHGetIconOverlayIndex が初めて呼び出されると、Shell はオーバーレイのファイル名とファイル内のインデックスを使用して、その画像をシステムイメージリストに追加します。オーバーレイがシステムイメージリストに追加された後は、Shell は単にファイル名とインデックスを識別子として使用します。SHGetIconOverlayIndex を使用して、いくつかの標準的なシステムオーバーレイのオーバーレイインデックスを取得することもできます。IShellIconOverlay::GetOverlayIndex は、単にオーバーレイインデックスを Shell に返します。IShellIconOverlay::GetOverlayIconIndex は、INDEXTOOVERLAYMASK マクロを使用して、オーバーレイインデックスを同等のイメージインデックスに変換する必要があります。

システムがサポートできる異なるアイコンオーバーレイハンドラーの数は、システムイメージリスト内でアイコンオーバーレイに利用できる領域の量によって制限されます。現在、アイコンオーバーレイには 15 個のスロットが割り当てられており、そのうちのいくつかはシステムによって予約されています。このため、アイコンオーバーレイは、満足のいく代替手段がない場合にのみ指定すべきです。

このインターフェイスは、オブジェクトに対してアイコンオーバーレイを指定する必要のある名前空間拡張によって実装されます。

このインターフェイスは、通常はアプリケーションでは使用されません。

システムイメージリスト内のオーバーレイインデックスを取得します。

型: HRESULT

このメソッドは、次のいずれかの値を返すことがあります。

システムイメージリスト内のオーバーレイインデックスを取得するには、SHGetIconOverlayIndex を呼び出します。

このメソッドを呼び出す際に pIndex が OI_ASYNC を指すように設定した場合、Shell のアイコンオーバーレイハンドラーは、オーバーレイインデックスを pIndex に格納する代わりに E_PENDING を返すことがあります。この戻り値は、オーバーレイの計算が低速な処理であり、バックグラウンドで処理すべきであることを示します。IShellIconOverlay の実装が E_PENDING を返すと、OI_ASYNC フラグなしでバックグラウンドのワーカースレッド上で再び呼び出されます。GetOverlayIndex を呼び出す際に OI_ASYNC を使用しない場合、オーバーレイハンドラーは戻る前にオーバーレイインデックスを計算し、その値を pIndex に格納する必要があります。

システムイメージリスト内のアイコンオーバーレイのインデックスを取得します。

型: HRESULT

このメソッドは、次のいずれかの値を返すことがあります。

システムイメージリスト内のオーバーレイのイメージインデックスを取得するには、まず SHGetIconOverlayIndex を呼び出してオーバーレイインデックスを取得する必要があります。次に、INDEXTOOVERLAYMASK マクロを使用して、オーバーレイインデックスを同等のイメージインデックスに変換します。