Pola Kontrol ItemContainer

Menjelaskan panduan dan konvensi untuk menerapkan IItemContainerProvider, termasuk informasi tentang metode. Pola kontrol ItemContainer digunakan untuk mendukung virtualisasi item.

Kontrol yang berisi sejumlah besar item anak dapat menggunakan virtualisasi untuk mengelola item secara efisien. Dengan virtualisasi, kontrol mempertahankan informasi lengkap dalam memori hanya untuk subset item pada waktu tertentu. Biasanya, subset hanya menyertakan item yang saat ini terlihat oleh pengguna. Informasi lengkap tentang item virtual yang tersisa disimpan dalam penyimpanan dan dimuat ke dalam memori, atau direalisasikan, karena kontrol membutuhkannya, misalnya, karena item baru terlihat oleh pengguna.

Misalnya, diagram berikut menunjukkan kotak daftar yang berisi ribuan item virtual. Karena kontrol mempertahankan informasi lengkap hanya untuk item anak yang saat ini terlihat, penyedia dapat mengekspos elemen Microsoft UI Automation hanya untuk item 100—127.

Kontrol yang menggunakan virtualisasi mewakili tantangan karena hanya item yang direalisasikan (de-virtualisasi) yang sepenuhnya tersedia sebagai elemen Automation UI di pohon Automation UI. Item tervirtualisasi tidak ada di pohon, sehingga informasi tentang item tersebut tidak tersedia.

Untuk memberikan informasi tentang item virtual, penyedia menerapkan pola kontrol ItemContainer , yang mengekspos antarmuka IItemContainerProvider . Metode FindItemByProperty menemukan item turunan berdasarkan nilai properti tertentu, seperti Nama, AutomationId, atau IsSelected. Jika item divirtualisasi, FindItemByProperty mengambil elemen tempat penampung Automation UI untuk item tersebut. Elemen tempat penampung adalah implementasi antarmuka IRawElementProviderSimple yang hanya mendukung pola kontrol VirtualizedItem .

Metode IVirtualizedItemProvider::Real memungkinkan klien untuk meminta agar item virtual direalisasikan, sehingga mengekspos elemen Automation UI lengkap untuk item sehingga semua properti dan pola yang diperlukan tersedia.

Meskipun tujuan utama pola kontrol ItemContainer adalah untuk mendukung skenario kontainer virtual, itu dapat diimplementasikan oleh kontainer apa pun yang mengambil item anak berdasarkan nama, terlepas dari apakah kontainer menggunakan virtualisasi.

Topik ini berisi bagian berikut.

• Panduan dan Konvensi Implementasi
• Anggota yang Diperlukan untuk IItemContainerProvider
• Topik terkait

Panduan dan Konvensi Implementasi

Saat menerapkan pola kontrol ItemContainer , perhatikan panduan dan konvensi berikut:

• Kontrol apa pun yang dapat berisi item virtual harus mendukung pola kontrol ItemContainer . Setiap kontainer yang mendukung pengambilan item berdasarkan nilai properti dapat mendukung pola ini, terlepas dari apakah kontainer menggunakan virtualisasi.
• Saat kontainer divirtualisasi, pola kontrol lain seperti Pilihan, Tabel, dan Kisi dapat terpengaruh. Misalnya, metode ISelectionProvider::GetSelection hanya dapat mendukung elemen yang ada di viewport, atau hanya elemen yang dipilih yang saat ini tidak divirtualisasi.
• Pola kontrol Gulir harus tidak terpengaruh oleh virtualisasi.
• Tidak ada jumlah item atau informasi indeks yang tersedia untuk item virtual. Kontrol virtual dapat menggunakan properti DescribedBy atau ItemStatus untuk memberikan informasi ini, jika perlu.
• Pengembang kontrol harus menkumentasikan dan menerbitkan detail semua properti Automation UI dan pola kontrol yang terpengaruh oleh penggunaan virtualisasi. Meskipun pola kontrol ItemContainer dan VirtualizedItem menawarkan dukungan dasar, pola kontrol tersebut mungkin tidak mendukung beberapa perilaku virtualisasi.

Panduan dan persyaratan berikut berlaku untuk metode IItemContainerProvider::FindItemByProperty .

• Meskipun tidak diperlukan, Microsoft sangat menyarankan agar FindItemByProperty mendukung properti Name, AutomationId, dan IsSelected .
• FindItemByProperty bisa lambat jika perlu melintasi beberapa objek untuk menemukan objek yang cocok.
• FindItemByProperty dapat dipanggil berulang kali untuk menemukan item secara berurutan. Item dapat dalam urutan apa pun selama setiap item dikembalikan hanya sekali.
• FindItemByProperty dapat diimplementasikan untuk menemukan hanya elemen yang muncul dalam tampilan kontrol atau konten pohon Automation UI. Elemen yang hanya muncul dalam tampilan mentah dapat dilewati untuk menghindari pengambilan beberapa elemen yang hanya mewakili sebagian dari "item" kepada pengguna.
• Ketika kriteria pencarian cocok dengan item virtual, penyedia dapat mengembalikan elemen tempat penampung yang mendukung pola kontrol VirtualizedItem . Panduan berikut berlaku untuk elemen tempat penampung:
  • Mengambil elemen tempat penampung untuk item virtual tidak boleh menyebabkan perubahan UI.
  • Elemen tempat penampung harus merupakan serekan dari elemen anak lainnya (diperlukan peristiwa yang diubah struktur).
  • Jika memungkinkan, penyedia dapat membuat elemen otomatisasi penuh alih-alih tempat penampung.
• Ketika kriteria pencarian cocok dengan elemen yang tidak divirtualisasikan, penyedia harus mengembalikan elemen aktual, bukan tempat penampung.
• Ketika tidak ada item yang ditemukan, IItemContainerProvider::FindItemByProperty harus mengatur parameter pFound ke NULL dan mengembalikan S_OK.
• Ketika parameter propertyId adalah 0, penyedia harus mengembalikan item berikutnya setelah pStartAfter.
• Jika parameter pStartAfter adalah NULL dan propertyId adalah 0, penyedia harus mengembalikan item pertama dalam kontainer.
• Ketika parameter propertyId adalah 0, parameter nilai diabaikan.

Panduan dan persyaratan berikut berlaku untuk elemen tempat penampung untuk item virtual di pohon Automation UI.

• Meskipun penyedia didorong untuk mendukung lebih banyak properti dan pola kontrol untuk elemen tempat penampung, hanya pola kontrol VirtualizedItem yang diperlukan.
• Penyedia dapat membatalkan elemen tempat penampung sebelumnya ketika IItemContainerProvider::FindItemByProperty dipanggil lagi. (Jika klien perlu mewujudkan elemen tempat penampung, itu harus segera melakukannya; jika tidak, elemen dapat dibatalkan jika FindItemByProperty dipanggil lagi atau jika viewport berubah karena alasan apa pun.)
• Tindakan UI seperti menggulir atau mengubah ukuran dapat menyebabkan viewport kontainer berubah dan sekumpulan item anak baru terlihat. Dalam hal ini, elemen tempat penampung yang diambil sebelumnya mungkin tidak tersedia di pohon Automation UI.
• Penyedia tidak boleh memvirtualisasi elemen UI yang tersedia di layar di viewport objek kontainer.

Anggota yang Diperlukan untuk IItemContainerProvider

Metode berikut diperlukan untuk mengimplementasikan antarmuka IItemContainerProvider .

Anggota yang diperlukan	Jenis anggota	Catatan
FindItemByProperty	Metode	Tidak ada

 

Pola kontrol ItemContainer tidak memiliki properti atau peristiwa terkait.

Topik terkait

Jenis Kontrol dan Pola Kontrol yang Didukung

Gambaran Umum Pola Kontrol UI Automation

Gambaran Umum Pohon UI Automation

Pola Kontrol VirtualizedItem