ItemContainer コントロール パターン

  • [アーティクル]

メソッドに関する情報など、 IItemContainerProvider を実装するためのガイドラインと規則について説明します。 ItemContainer コントロール パターンは、項目の仮想化をサポートするために使用されます。

多数の子項目を含むコントロールは、仮想化を使用して項目を効率的に管理できます。 仮想化を使用すると、コントロールは、特定の時点で項目のサブセットに対してのみ完全な情報をメモリ内に保持します。 通常、サブセットには、ユーザーに現在表示されている項目のみが含まれます。 残りの仮想化された項目に関する完全な情報は、ストレージに保持され、メモリに読み込まれるか、またはコントロールが必要とするように認識されます(たとえば、新しい項目がユーザーに表示されるようになる)。

たとえば、次の図は、何千もの仮想化された項目を含むリスト ボックスを示しています。 コントロールは現在表示されている子項目に対してのみ完全な情報を保持するため、プロバイダーはアイテム 100 - 127 に対してのみ Microsoft UI オートメーション要素を公開できます。

仮想化され、仮想化されていないリスト ボックス内の項目を示す図

仮想化を使用するコントロールは、UI オートメーション ツリーのUI オートメーション要素として実現 (仮想化解除) 項目のみが完全に使用できるため、課題を表します。 仮想化された項目はツリーに存在しないため、それらに関する情報は使用できません。

仮想化された項目に関する情報を提供するために、プロバイダーは 、IItemContainerProvider インターフェイスを公開する ItemContainer コントロール パターンを実装します。 FindItemByProperty メソッドは、Name、AutomationId、IsSelected などの特定のプロパティの値に基づいて子項目を検索します。 アイテムが仮想化されている場合、FindItemByProperty はアイテムのUI オートメーションプレースホルダー要素を取得します。 プレースホルダー要素は、VirtualizedItem コントロール パターンのみをサポートする IRawElementProviderSimple インターフェイスの実装です。

IVirtualizedItemProvider::Realize メソッドを使用すると、クライアントは仮想化された項目の実現を要求できるため、必要なすべてのプロパティとパターンを使用できるように、アイテムの完全なUI オートメーション要素が公開されます。

ItemContainer コントロール パターンの主な目的は仮想化コンテナー のシナリオをサポートすることですが、コンテナーが仮想化を使用しているかどうかに関係なく、名前で子項目を取得する任意のコンテナーで実装できます。

このトピックは、次のセクションで構成されています。

実装のガイドラインと規則

ItemContainer コントロール パターンを実装する場合は、次のガイドラインと規則に注意してください。

  • 仮想化された項目を含めることができるコントロールは、 ItemContainer コントロール パターンをサポートする必要があります。 プロパティ値に基づく項目の取得をサポートするすべてのコンテナーは、コンテナーが仮想化を使用しているかどうかに関係なく、このパターンをサポートできます。
  • コンテナーが仮想化されると、 Selection、 Table、 Grid などの他のコントロール パターンが影響を受ける可能性があります。 たとえば、 ISelectionProvider::GetSelection メソッドは、ビューポート内の要素のみ、または現在仮想化されていない選択された要素のみをサポートする場合があります。
  • スクロール コントロール パターンは仮想化の影響を受けません。
  • 仮想化されたアイテムに対して項目数またはインデックス情報を使用できません。 仮想化されたコントロールは、必要に応じて 、DescribedBy または ItemStatus プロパティを使用してこの情報を提供できます。
  • コントロール開発者は、仮想化の使用の影響を受けるすべてのUI オートメーションプロパティとコントロール パターンの詳細を文書化して公開する必要があります。 ItemContainer コントロール パターンと VirtualizedItem コントロール パターンでは基本的なサポートが提供されますが、一部の仮想化動作はサポートされない場合があります。

IItemContainerProvider::FindItemByProperty メソッドには、次のガイドラインと要件が適用されます。

  • 必須ではありませんが、 FindItemByProperty でName、 AutomationId、 IsSelected プロパティをサポートすることを強くお勧めします。
  • FindItemByProperty は、一致するオブジェクトを見つけるために複数のオブジェクトを走査する必要がある場合、低速になる可能性があります。
  • FindItemByProperty は、アイテムを順番に検索するために繰り返し呼び出すことができます。 各項目が 1 回だけ返される限り、アイテムは任意の順序で指定できます。
  • FindItemByProperty は、UI オートメーション ツリーのコントロールビューまたはコンテンツ ビューに表示される要素のみを検索するために実装できます。 未加工のビューにのみ表示される要素はスキップして、ユーザーに対する "項目" の一部のみを表す複数の要素を取得しないようにすることができます。
  • 検索条件が仮想化された項目と一致する場合、プロバイダーは VirtualizedItem コントロール パターンをサポートするプレースホルダー要素を返すことができます。 プレースホルダー要素には、次のガイドラインが適用されます。
    • 仮想化された項目のプレースホルダー要素を取得すると、UI が変更される可能性はありません。
    • placeholder 要素は、他の子要素のピアである必要があります (構造体変更イベントが必要です)。
    • 可能であれば、プロバイダーはプレースホルダーの代わりに完全なオートメーション要素を作成できます。
  • 検索条件が仮想化されていない要素と一致する場合、プロバイダーはプレースホルダーではなく実際の要素を返す必要があります。
  • 項目が見つからない場合、 IItemContainerProvider::FindItemByProperty は pFound パラメーターを NULL に設定し、 S_OKを返す必要があります。
  • propertyId パラメーターが 0 の場合、プロバイダーは pStartAfter の後に次の項目を返す必要があります。
  • pStartAfter パラメーターが NULL で propertyId が 0 の場合、プロバイダーはコンテナー内の最初の項目を返す必要があります。
  • propertyId パラメーターが 0 の場合、value パラメーターは無視されます。

次のガイドラインと要件は、UI オートメーション ツリー内の仮想化された項目のプレースホルダー要素に適用されます。

  • プロバイダーは、プレースホルダー要素に対してより多くのプロパティとコントロール パターンをサポートすることをお勧めしますが、 VirtualizedItem コントロール パターンのみが必要です。
  • プロバイダーは、 IItemContainerProvider::FindItemByProperty が再度呼び出されたときに、以前のプレースホルダー要素を無効にすることができます。 (クライアントがプレースホルダー要素を認識する必要がある場合は、すぐに行う必要があります。それ以外の場合は、 FindItemByProperty が再び呼び出された場合、または何らかの理由でビューポートが変更された場合、要素を無効にすることができます)。
  • スクロールやサイズ変更などの UI アクションにより、コンテナーのビューポートが変更され、子項目の新しいセットが表示される可能性があります。 この場合、以前に取得したプレースホルダー要素は、UI オートメーション ツリーで使用できない可能性があります。
  • プロバイダーは、コンテナー オブジェクトのビューポートで画面上で使用できる UI 要素を仮想化しないでください。

IItemContainerProvider の必須メンバー

IItemContainerProvider インターフェイスを実装するには、次のメソッドが必要です。

必須メンバー メンバーの型 メモ
FindItemByProperty 方法 なし

 

ItemContainer コントロール パターンには、関連付けられたプロパティやイベントはありません。

コントロール型とそのサポートされているコントロール パターン

UI オートメーション コントロール パターンの概要

UI オートメーション ツリーの概要

VirtualizedItem コントロール パターン