ICustomDestinationList

タスクバーに表示するための、宛先(destination)やタスクを含むカスタムジャンプリストをアプリケーションが提供できるようにするメソッドを公開します。

実装するタイミング

使用するタイミング

• 宛先(Destinations) は、個々の利用状況に基づいて 最近使ったもの、よく使うもの、またはカスタムカテゴリに表示される項目です。宛先はファイル、フォルダー、Web サイト、その他のコンテンツベースの項目になり得ますが、必ずしもファイルを裏付けとするものではありません。宛先は「もの」や名詞と考えることができます。宛先はユーザーによってジャンプリストにピン留めしたり、削除したりできます。宛先は一般に IShellItem オブジェクトで表されますが、IShellLink オブジェクトで表される場合もあります。
• タスク(Tasks) は、個々の利用パターンに関係なく、そのアプリケーションのすべてのユーザーに適用される、アプリケーションで実行される一般的な操作です。タスクは「アクション」や動詞と考えることができます。タスクはピン留めや削除ができません。タスクは IShellLink オブジェクトで表されます。

タスクバーは各タスクバーボタンにジャンプリストを提供します。既定では、ジャンプリストには 最近使ったもの カテゴリが含まれ、ファイルベースのアプリケーションでは SHAddToRecentDocs または共通ファイルダイアログを通じて自動的に設定されます。最近使ったもの カテゴリを よく使うもの カテゴリに置き換えたり、独自のカスタムカテゴリを定義・追加・設定したりするには、アプリケーションはこのインターフェースのメソッドを呼び出す必要があります。アプリケーションはまた、そのアーキテクチャや意図された用途に基づいて独自のタスクを提供することもできます。

アプリケーションはタスクバー UI にカスタムジャンプリストを提供するために、このオブジェクトを呼び出す必要があります。システムがアプリケーションにその情報を問い合わせることは決してありません。

アプリケーションがカスタムジャンプリストを提供する場合、そのリストに関する一定の責任を負います。カスタムカテゴリはジャンプリストの意図された用途に沿った方法で設定する必要があります。リスト内の項目は有効性を確認するか、削除されていた場合には適切に失敗するようにしなければなりません。ユーザーがリストから項目を削除した場合、その削除は尊重されなければなりません。

カスタムジャンプリストは、既存のリスト内の要素を変更するという意味で真に更新されることは決してありません。むしろ、古いリストが新しいリストに置き換えられます。

カスタムジャンプリストを構築して表示するための ICustomDestinationList メソッド呼び出しの基本的な順序は次のとおりです。

1. SetAppID(アプリケーションが独自の AppUserModelID を提供する場合にのみ必要)
2. BeginList
3. AppendCategory、AppendKnownCategory、AddUserTasks、またはこれら 3 つのメソッドの任意の組み合わせ。
4. CommitList

このインターフェースのメソッドを通じて構築されるカスタムジャンプリストを、タスクバーボタンに保持するアプリケーションに対して、一意の Application User Model ID(AppUserModelID)を指定します。このメソッドは省略可能です。

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

アプリケーションが明示的な AppUserModelID を持つ場合、ICustomDestinationList::BeginList または ICustomDestinationList::GetRemovedDestinations を呼び出す前に SetAppID を呼び出す必要があります。

オブジェクトの SetAppID メソッドを通じて AppUserModelID が指定された後、その AppUserModelID は、別の SetAppID の呼び出しで上書きされない限り、そのオブジェクトの有効期間中オブジェクト内に保存されます。

一部のアプリケーションは明示的な AppUserModelID を宣言せず、このメソッドを呼び出すべきではありません。その場合、アプリケーションの識別情報は ICustomDestinationList::BeginList または ICustomDestinationList::GetRemovedDestinations が呼び出されたときに推定されます。しかし、こうした計算を回避することにはパフォーマンス上の利点があるため、カスタムジャンプリストを提供するアプリケーションは 明示的な AppUserModelID を使用することが推奨されます。

カスタムジャンプリストの構築セッションを開始します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

アプリケーションが明示的な Application User Model ID(AppUserModelID)を持つ場合、このメソッドを呼び出す前に ICustomDestinationList::SetAppID を呼び出す必要があります。

ppv パラメーターで取得される IObjectArray インターフェースは、GetRemovedDestinations を通じて取得されるものと同じ削除済み宛先リストを表します。新しいジャンプリストを生成する際、アプリケーションはまず削除済み宛先を処理しなければなりません。削除済みリスト内の項目の追跡データはすべてクリアする必要があります。この削除済み宛先リストに存在する項目を AppendCategory を通じて含めようとすると、その AppendCategory 呼び出しは失敗します。これにより、削除された項目に関するユーザーの選択をアプリケーションが尊重することが保証されます。BeginList 以降、削除された項目の再追加を試みたことによる AppendCategory の失敗した呼び出しがない状態で CommitList の呼び出しが行われた後、削除済み宛先リストはクリアされます。その後、ユーザーが引き続きその項目を使用すれば、以前に削除された項目が宛先リストに戻る場合があります。

AppendCategory、AppendKnownCategory、または AddUserTasks を通じてリストの内容を設定する呼び出しを行う前に、リストを開始するために BeginList を呼び出す必要があります。

カスタムジャンプリストに含めるための、カスタムカテゴリとそれに含まれる宛先を定義します。

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合はエラー値を返します。

AppendCategory の呼び出しが、セッションを開始した BeginList の呼び出しによって取得された削除済み宛先リストに含まれる項目を追加しようとした場合、AppendCategory の呼び出しは失敗します。

AppendCategory が、アプリケーションが処理するように登録されていない IShellItem を追加しようとした場合、呼び出しは失敗します。

プライバシーに関するグループポリシーまたはユーザーのプライバシー設定が有効になっている場合、AppendCategory は失敗することがあります。カスタムカテゴリには個々の利用状況に基づくユーザー固有の項目が含まれますが、これはそうしたプライバシー設定では許可されません。

プライバシーに関するグループポリシーまたはユーザーのプライバシー設定は、他の ICustomDestinationList メソッドで失敗を引き起こすことはありません。タスクはユーザー固有ではありません。AppendKnownCategory は、データがないため 最近使ったもの または よく使うもの カテゴリを表示させませんが、メソッド呼び出しは失敗コードを返しません。

プライバシーに関するグループポリシーまたはユーザーのプライバシー設定に起因する AppendCategory の失敗コード(E_ACCESSDENIED)の場合、アプリケーションは引き続きタスクを更新し、CommitList を呼び出す必要があります。

関連付けられたアプリケーションのファイル種類登録が見つからなかった場合、AppendCategory は HRESULT 0x80040F03 を返します。これは、アプリケーションがジャンプリストに追加しようとしているファイル種類を登録していないこと、または、アプリケーションが明示的な AppUserModelID を使用しているときに AppUserModelID を提供していないなど、登録上の問題から生じることがあります。

このメソッドを呼び出す前に BeginList を呼び出す必要があります。

アプリケーションがカスタムカテゴリを提供する場合、そのアプリケーションはカテゴリの内容を設定する責任を負います。カテゴリの内容は依然としてユーザー固有であり、ユーザーの履歴やアクションに基づくべきですが、カスタムカテゴリを使用することで、アプリケーションは何を追跡し何を無視するかを決定できます。たとえば、異なるアプリケーションオプションが選択されると、異なるシナリオが関係することがあります。たとえば、オーディオプログラムは、最近再生したアルバムのみを含め、最近再生した個々のトラックは無視することを選択できます。アプリケーションは、システムの既定のアルゴリズムよりも優れた結果をもたらす、その特定の用途に合わせた利用状況追跡アルゴリズムを単に備えている場合もあります。

アプリケーションは、1 回のリスト構築セッションで複数のカスタムカテゴリを追加するために AppendCategory を複数回呼び出すことができます。この場合、カテゴリの内容が相互に排他的になるように設計すべきです。各カスタムカテゴリは特定のシナリオを中心に構築し、項目がそれらの間で重複しないようにする必要があります。

カスタムジャンプリスト内のカテゴリは、既知の 最近使ったもの または よく使うもの カテゴリを含め、追加された順に表示され、最も新しく追加された項目がリストの末尾に配置されます。すべてのエントリを表示するのに十分なスペースがない場合、リストの最後のエントリから先に画面外に消えていきます。したがって、最も重要なカテゴリを最初に追加して、常に表示される可能性を最大限に高めるべきです。カテゴリ内の宛先は、poa が指す IObjectArray オブジェクトに格納されている順に表示されます。

ユーザーは、カスタムカテゴリで提供された宛先の 1 つ以上をジャンプリストにピン留めすることを選択する場合があります。ピン留めされた宛先のリストはアプリケーションからは利用できませんが、重複は UI によって防止されるため、アプリケーション側で追加の操作は不要です。視覚的には、ピン留めされた項目はジャンプリストの ピン留め セクションに移動し、元の場所からは消えます。

AppendCategory の呼び出しが成功しても、それらの項目が表示される保証はありません。ICustomDestinationList::BeginList の pcMinItems パラメーターが指す値を超えて追加された宛先は表示されません。ピン留め カテゴリは他のすべての宛先リストより優先されます。ピン留め リストが表示され、その後、残りのスペースが他の宛先リストに割り当てられます。ユーザーが十分な数の宛先をジャンプリストにピン留めすることで、他の宛先が表示されなくなる可能性があります。画面解像度の低下やフォントサイズの拡大などの他の要因も、アプリケーションが提供する宛先がリストから切り捨てられる原因となることがあります。アプリケーションはこれらの状況を予測する手段を持たず、発生時に通知されることもありません。アプリケーションは、その可能性が存在することを認識しておかなければなりません。宛先リストの切り捨ては下から上へと発生するため、アプリケーションは最も重要なカテゴリと宛先をリストの上部に配置し、表示される可能性を最大化すべきです。

BeginList で開始し CommitList で終了するセッション中に、AppendCategory を複数回呼び出す場合があります。それらの呼び出しのいずれか 1 つでも、削除済み項目リストに含まれる項目を含むカテゴリを追加しようとして失敗した場合、CommitList の呼び出しは削除済み項目リストをクリアしません。削除済み項目リストをクリアするには、セッション中のすべての AppendCategory 呼び出しが成功して返る必要があります。

poa が指す IObjectArray を通じて提供される IShellLink インスタンスは、次を提供しなければなりません。

• 項目識別子リスト(PIDL)へのポインター(SetIDList)、またはターゲットパス(SetPath または SetRelativePath)のいずれか
• コマンドライン引数(SetArguments)
• アイコンの場所(SetIconLocation)

必要に応じて、ジャンプリスト内の項目にカスタムツールチップを提供するために、説明フィールド(SetDescription)を設定できます。

よく使うもの(Frequent)または最近使ったもの(Recent)カテゴリをカスタムジャンプリストに含めることを指定します。

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合はエラー値を返します。

プライバシーに関するグループポリシーまたはユーザーのプライバシー設定が存在する場合、このメソッドの結果に影響することがあります。個々の利用状況に基づくユーザー固有の項目を含むカテゴリは、そうしたプライバシー設定では許可されません。このため、このメソッドを通じて追加された 最近使ったもの または よく使うもの カテゴリはデータを持たず、データのないカテゴリは表示されません。ただしその場合でも、このメソッド呼び出しは失敗コードにはなりません。

このメソッドを呼び出す前に ICustomDestinationList::BeginList を呼び出す必要があります。

最近使ったもの カテゴリは既定のジャンプリストに表示されますが、カスタムカテゴリと共にカスタムジャンプリストに表示するには、このメソッドを通じて明示的に要求する必要があります。

AppendCategory と AppendKnownCategory の両方において、カスタムジャンプリストは、いずれの項目も複数のカテゴリに表示されないように設計すべきです。2 つのカテゴリが同じデータを単に異なる視点で表示しているだけの場合、一方のカテゴリはユーザーの利便性に寄与せずジャンプリストのスペースを使用しているため、削除すべきです。重複はシステムによって非表示にはされません。ただし、ピン留めされた宛先の場合は例外で、その宛先はピン留めカテゴリに表示され、他のすべてのカテゴリでは非表示になります。

よく使うもの カテゴリと 最近使ったもの カテゴリはある程度重複する可能性が高いため、両方のカテゴリを 1 つのジャンプリストに追加すべきではありません。この 2 つのうちどちらがアプリケーションに適しているかは、その性質によります。Microsoft Word や Microsoft Paint のようにファイルを生成するアプリケーションは、ユーザーが最近作業したファイルに戻りたい可能性が最も高いため、最近使ったもの カテゴリを使用すべきです。他所で作成されたデータの閲覧や再生に多く使用されるアプリケーションは、ユーザーがより多くの項目にアクセスし、その多くが 1 回限りである可能性が高いため、よく使うもの カテゴリを使用すべきです。言い換えると、アプリケーションが多数の項目にそれぞれ数回だけアクセスする可能性が高く、それがユーザーが何度もアクセスしたいより小さな項目集合にとってノイズとなる場合は、よく使うもの が最適な選択です。アプリケーションがより少数の新しい項目にほとんどの場合アクセスする可能性が高い場合は、最近使ったもの を選択すべきです。

カスタムジャンプリスト内のカテゴリは、既知の 最近使ったもの または よく使うもの カテゴリを含め、追加された順に表示され、最も新しく追加されたカテゴリがリストの下部に配置されます。

ICustomDestinationList::BeginList の pcMinItems パラメーターが指す値を超えて追加された宛先は表示されません。

空のカテゴリは表示されません。

よく使うもの および 最近使ったもの カテゴリの内容は、SHAddToRecentDocs を直接使用する各アプリケーションについて計算されます。Windows エクスプローラーを通じてファイルを開く場合や、共通ファイルダイアログボックスを使ってファイルを開く・保存する・作成する場合など、一部のユーザー操作では、シェルがアプリケーションに代わって SHAddToRecentDocs を呼び出し、それらの呼び出しも利用統計に考慮されます。宛先がジャンプリストから起動されたときも、シェルはアプリケーションに代わって SHAddToRecentDocs を呼び出します。ただし、シェルが呼び出すことが予想される場合でも、アプリケーション自身が明示的に SHAddToRecentDocs を呼び出すのは良い習慣です。これにより利用状況が確実に記録され、最近使ったもの・よく使うものの追跡アルゴリズムが重複呼び出しを補正します。

カスタムジャンプリストのタスクカテゴリに含める項目を指定します。

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合はエラー値を返します。

このメソッドを呼び出す前に ICustomDestinationList::BeginList を呼び出す必要があります。

タスク カテゴリのヘッダーは、カテゴリが空でない限り、既定で常にリストに表示されます。このヘッダーテキストは変更できません。ユーザーが選択した言語で表示されます。

タスク カテゴリは、ジャンプリストで常に最後のカテゴリとして表示されますが、リスト内の他のすべてのカテゴリより優先されます。このリストが埋められ、その後、残りのスペースが他のカテゴリに割り当てられます。他のカテゴリとは異なり、タスク カテゴリ内の項目はユーザーによる削除やピン留めができません。アプリケーションは、このカテゴリ内のタスクがユーザーにもたらす価値と、他のカテゴリに必要なスペースとのバランスを取る必要があります。

タスクはアプリケーション全体に適用されるべきものであり、個々のウィンドウやドキュメントに固有のものであることを意図していません。より粒度の細かいコンテキスト依存のタスクについては、アプリケーションは サムネイルツールバー を通じて提供できます。

poa が指す IObjectArray を通じて提供される IShellLink インスタンスは、次を提供しなければなりません。

• 項目識別子リスト(PIDL)へのポインター(SetIDList)、またはターゲットパス(SetPath または SetRelativePath)のいずれか
• コマンドライン引数(SetArguments)
• アイコンの場所(SetIconLocation)

必要に応じて、ジャンプリスト内の項目にカスタムツールチップを提供するために、説明フィールド(SetDescription)を設定できます。

タスクリストには区切り記号を含めることもできます。これらは、空の IShellLink を含め(これは引数リスト要件の唯一の例外です)、その System.AppUserModel.IsDestListSeparator プロパティを IShellLink オブジェクトの IPropertyStore インターフェースを通じて TRUE に設定することで作成します。IShellLink 内の他の値はすべて無視されます。区切り記号はリスト内で 1 つ分のスペースを占有せず、リスト内の項目数にはカウントされません。間に項目のない 2 つの区切り記号が指定された場合、一方の区切り記号は表示されません。リストの先頭または末尾にある区切り記号も無視されます。

ICustomDestinationList::BeginList の呼び出しによって開始されたジャンプリストが完成し、表示の準備ができたことを宣言します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このセッション中の AppendCategory の呼び出しが、削除された項目を含めようとして失敗していない限り、CommitList を呼び出すと、格納されていた削除済み項目リストがクリアされ、新しい削除済み項目リストが開始されます。

このカスタムジャンプリストが置き換える対象となる既存のジャンプリストから、ユーザーによって削除された宛先の現在のリストを取得します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

項目はユーザー操作によってジャンプリスト UI から削除できます。すると項目は削除済みとしてマークされ、以後表示されなくなります。アプリケーションはこのメソッドを使用して、ユーザーがどの項目を削除したかを把握し、それらを独自のリストに表示しないようにできます。たとえば、アプリケーションが ICustomDestinationList::BeginList を通じて新しいリストを生成しない場合、そのアプリケーションの起動時にこのメソッドを呼び出すべきです。

ユーザーが宛先の削除を選択したときは、その宛先の追跡データをすべてクリアすることを強く推奨します。ユーザーが将来その宛先に再びアクセスした場合、宛先がジャンプリストに再追加され、再びデータを蓄積できます。このメソッドで取得される削除済み宛先リストと同じものが、ICustomDestinationList::BeginList が呼び出されたときに取得されます。その場合、アプリケーションは削除された項目をすぐに再挿入しようとしてはなりません。そうしないと AppendCategory の呼び出しが失敗します。これにより、項目を削除するというユーザーの意図をアプリケーションが尊重することが保証されます。

アプリケーションが明示的な Application User Model ID(AppUserModelID)を持つ場合、このメソッドを呼び出す前に SetAppID を呼び出す必要があります。

アプリケーションが GetRemovedDestinations を呼び出し、新しいカスタムジャンプリストが作成されると予想されるよりも早くジャンプリストに復元される可能性が高い項目をリスト内に見つけたとしても、アプリケーションはその項目を含めずにジャンプリストを書き込み、ユーザーが再びその項目にアクセスした後にのみリストへ再追加すべきです。

アプリケーションは、最近使ったもの または よく使うもの の 既知のカテゴリ をカスタムジャンプリストに追加できます。そのカテゴリ内の項目は、いずれのカスタムカテゴリにも表示されていなかったとしても、削除済み項目リストに含まれている場合があります。その場合でも、アプリケーションはその項目について利用データが保存されていたのであれば、それをクリアすべきです。

GetRemovedDestinations の呼び出しは、削除済み宛先データをクリアしません。このデータは、次回のリスト生成のために BeginList によって必要とされます。削除済み宛先データは、BeginList によってリスト生成セッションが開始され、失敗する AppendCategory 呼び出しなしに継続され、CommitList の呼び出しによって完了した後、不要になりクリアされます。

指定したアプリケーションのカスタムジャンプリストを削除します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このメソッドを呼び出すべき状況はいくつかあり、次を含みます。

• アプリケーションがアンインストールされるとき。
• ユーザーがアプリケーション内から履歴を消去するとき。
• ユーザーがアプリケーションの設定またはオプションのページで宛先の追跡を無効にするとき。

カスタムジャンプリストが削除された後は、最近使用した項目のシステム生成データから生成された標準のジャンプリストが表示されます。そのようなデータが収集されていない場合、または RemoveAllDestinations によって情報が消去されている場合、ジャンプリストには、その最小限の常に存在するコンテンツ、すなわちピン留め/ピン留め解除、アプリケーションの新しいインスタンスの起動、ウィンドウを閉じるといった標準タスクのみが含まれる可能性があります。

ICustomDestinationList::BeginList によって開始されたジャンプリスト構築セッションを、変更をコミットせずに中止します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このメソッドにより、アプリケーションは 1 つの ICustomDestinationList オブジェクトを多数のトランザクションに使用できます。新しいデータをコミットしたり、以前に格納されたリストを破棄したりすることなくセッションを終了できるためです。