ICustomDestinationList::AppendCategory メソッド (shobjidl_core.h)
カスタム ジャンプ リストに含めるために、カスタム カテゴリとそのカテゴリに含まれる変換先を定義します。
構文
HRESULT AppendCategory(
[in] LPCWSTR pszCategory,
[in] IObjectArray *poa
);
パラメーター
[in] pszCategory
種類: LPCWSTR
カスタム カテゴリの表示名を含む文字列へのポインター。 この文字列は、ジャンプ リストのカテゴリのヘッダーに表示されます。 文字列は表示名を直接保持することも、"@shell32.dll,-1324" などの間接的な文字列表現を使用して格納された文字列を使用することもできます。 間接文字列を使用すると、カテゴリ ヘッダーをユーザーの選択した言語で表示できます。
[in] poa
種類: IObjectArray*
カテゴリ内の宛先を表す 1 つ以上の IShellItem オブジェクトを表す IObjectArray へのポインター。 リスト内の一部の変換先は 、IShellLink オブジェクトによって表されることもありますが、頻度は低くなります。
戻り値
種類: HRESULT
成功した場合はS_OKを返し、それ以外の場合はエラー値を返します。
AppendCategory の呼び出しで、セッションを開始した BeginList の呼び出しによって取得された削除された宛先リスト内の項目を追加しようとすると、AppendCategory の呼び出しは失敗します。
AppendCategory が、アプリケーションが処理するために登録されていない IShellItem を追加しようとすると、呼び出しは失敗します。
AppendCategory は、プライバシー グループ ポリシーまたはユーザー のプライバシー設定が有効になっている場合に失敗する可能性があります。 カスタム カテゴリには、個々の使用状況に基づくユーザー固有のアイテムが含まれます。これらのプライバシー設定では許可されません。
プライバシー グループ ポリシーまたはユーザー プライバシー設定では、他の ICustomDestinationList メソッドでエラーが発生することはありません。 タスクはユーザー固有ではありません。 AppendKnownCategory では、データがないため Recent カテゴリまたは Frequent カテゴリは表示されませんが、メソッド呼び出しではエラー コードは返されません。
AppendCategory で、プライバシーグループ ポリシーまたはユーザー プライバシー設定 (E_ACCESSDENIED) によって発生したエラー コードの場合、アプリケーションはタスクを更新し、CommitList を呼び出す必要があります。
関連付けられたアプリケーションのファイルの種類の登録が見つからなかった場合、 AppendCategory は HRESULT 0x80040F03を返します。 これは、ジャンプ リストに追加しようとしているファイルの種類をアプリケーションが登録しないか、登録の問題 (アプリケーションが明示的な AppUserModelID を使用しているときに AppUserModelID を指定しないなど) によって発生する可能性があります。
解説
このメソッドを呼び出す前に BeginList を呼び出す必要があります。
アプリケーションがカスタム カテゴリを提供する場合、そのアプリケーションはユーザー設定の責任を負います。 カテゴリの内容は引き続きユーザー固有であり、ユーザーの履歴とアクションに基づく必要がありますが、カスタム カテゴリを使用することで、アプリケーションは追跡する対象と無視する内容を決定できます。 たとえば、異なるアプリケーション オプションを選択すると、さまざまなシナリオが関係する可能性があります。 たとえば、オーディオ プログラムでは、最近再生したアルバムのみを含め、最近再生された個々のトラックを無視するように選択できます。 また、アプリケーションには、システムの既定のアルゴリズムよりも優れた結果を提供する、特定の用途に合わせた使用状況追跡アルゴリズムが用意されている場合もあります。
アプリケーションは、リスト構築セッションで AppendCategory を複数回呼び出して、複数のカスタム カテゴリを追加できます。 この場合、カテゴリは、コンテンツが相互に排他的になるように設計する必要があります。 各カスタム カテゴリは、アイテムがそれらの間で重複しないように、特定のシナリオを中心に構築する必要があります。
カスタムジャンプリストのカテゴリ (既知の 最近 のカテゴリや 頻繁 なカテゴリを含む) は、追加された順序で表示され、リストの末尾に最新の項目が追加されます。 すべてのエントリを表示するのに十分な領域がない場合は、一覧の最後のエントリが最初に画面から消えます。 したがって、常に表示される可能性を最大限に高めるために、最も重要なカテゴリを最初に追加する必要があります。 カテゴリ内の宛先は、poa が指す IObjectArray オブジェクトに格納される順序で表示されます。
ユーザーは、カスタム カテゴリで指定された 1 つ以上の宛先をジャンプ リストにピン留めする場合があります。 ピン留めされた宛先の一覧はアプリケーションでは使用できませんが、UI によって重複が防止されるため、アプリケーションに追加のアクションは必要ありません。 視覚的には、ピン留めされた項目はジャンプ リストの [固定] セクションに移動し、元の場所から消えます。
AppendCategory を正常に呼び出しても、それらの項目が表示される保証はありません。 ICustomDestinationList::BeginList の pcMinItems パラメーターによって指される値に対して追加された宛先の数は表示されません。 ピン留めされたカテゴリは、他のすべての宛先リストよりも優先されます。 ピン留めされたリストが表示され、残りの領域が他の宛先リストに割り当てられます。 ユーザーがジャンプ リストに十分な宛先をピン留めして、他の宛先が表示されないようにすることができます。 画面の解像度の低下やフォント サイズの増加など、その他の要因により、アプリケーションが指定した宛先が一覧から切り捨てられる場合もあります。 アプリケーションにはこれらの状況を予測する方法がなく、発生しても通知されません。 アプリケーションは、可能性が存在することを認識する必要があります。 宛先リストまたはリストの切り捨ては一番下から行われるため、アプリケーションは最も重要なカテゴリと宛先をリストの一番上に配置して、表示される可能性が最も高くなります。
BeginList で開始され、CommitList で終わるセッションでは、AppendCategory を複数回呼び出す場合があります。 削除されたアイテムリストにアイテムを含むカテゴリを追加しようとして、これらの呼び出しのいずれかが失敗した場合、 CommitList の呼び出しでは削除されたアイテムリストはクリアされません。 削除された項目リストをクリアするには、セッション内の AppendCategory のすべての呼び出しが正常に返される必要があります。
poa が指す IObjectArray を介して提供される IShellLink インスタンスは、次を提供する必要があります。
- 項目識別子リスト (PIDL) へのポインター (SetIDList) またはターゲット パス (SetPath または SetRelativePath) のいずれか
- コマンド ライン引数 (SetArguments)
- アイコンの場所 (SetIconLocation)
必要に応じて、説明フィールド (SetDescription) を設定して、ジャンプ リスト内のアイテムのカスタム ヒントを提供できます。
要件
| サポートされている最小のクライアント | Windows 7 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 R2 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | shobjidl_core.h (Shobjidl.h を含む) |
| Library | Shell32.lib |
| [DLL] | Shell32.dll (バージョン 6.1 以降) |
関連項目
ICustomDestinationList::AddUserTasks
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示