Pola Kontrol Text dan TextRange
Menjelaskan panduan dan konvensi untuk menerapkan ITextProvider, ITextProvider2, dan ITextRangeProvider, termasuk informasi tentang properti dan metode. Pola kontrol Teks memungkinkan aplikasi dan kontrol untuk mengekspos model objek teks sederhana, memungkinkan klien untuk mengambil konten tekstual, atribut teks, dan objek yang disematkan dari kontrol berbasis teks.
Untuk mendukung pola kontrol Teks , kontrol mengimplementasikan antarmuka ITextProvider dan ITextProvider2 . Jenis kontrol yang harus mendukung pola Kontrol teks mencakup jenis kontrol Edit dan Dokumen , dan jenis kontrol lainnya yang memungkinkan pengguna memasukkan teks atau memilih teks baca-saja.
Pola kontrol Teks dapat digunakan dengan pola kontrol Microsoft UI Automation lainnya untuk mendukung beberapa jenis objek yang disematkan dalam teks, termasuk tabel, hyperlink, dan tombol perintah.
Antarmuka ITextProvider dan ITextProvider2 mencakup sejumlah metode untuk memperoleh rentang teks. Rentang teks adalah objek yang mewakili rentang teks yang berdampingan—atau beberapa, rentang teks yang tidak terputang—dalam kontainer teks. Satu metode ITextProvider memperoleh rentang teks yang mewakili seluruh dokumen, sementara yang lain memperoleh rentang teks yang mewakili beberapa bagian dokumen, seperti teks yang dipilih, teks yang terlihat, atau objek yang disematkan dalam teks.
Objek rentang teks diwakili oleh pola kontrol TextRange , yang diimplementasikan melalui antarmuka ITextRangeProvider . Pola kontrol TextRange menyediakan metode dan properti yang digunakan untuk mengekspos informasi tentang teks dalam rentang, memindahkan titik akhir rentang, memilih atau membatalkan pilihan teks, menggulir rentang ke tampilan, dan sebagainya.
Untuk informasi selengkapnya tentang pola kontrol Teks dan TextRange , lihat Dukungan Automasi UI untuk Konten Tekstual.
Dimulai dengan penyedia Windows 8.1 dapat mengimplementasikan antarmuka ITextRangeProvider2. Ini memungkinkan pemanggilan menu konteks yang terkait dengan rentang teks. Ini mendukung skenario seperti koreksi otomatis teks atau pemilihan kandidat Editor Metode Input (IME).
Topik ini berisi bagian berikut.
- Panduan dan Konvensi Implementasi
- Anggota yang Diperlukan untuk ITextProvider
- Anggota yang Diperlukan untuk ITextRangeProvider
- Rentang Teks Pendukung
- Interoperabilitas dengan System Caret
- Topik terkait
Panduan dan Konvensi Implementasi
Saat menerapkan pola kontrol Teks , perhatikan panduan dan konvensi berikut:
- Kontrol apa pun yang memungkinkan akses ke teks (misalnya, memasukkan teks atau memilih teks baca-saja) harus mendukung pola kontrol Teks .
- Pola kontrol Teks dapat digunakan dengan elemen UI apa pun yang menyajikan teks, bahkan label statis pada kontrol tombol standar. Namun, tidak diperlukan pada kontrol teks statis yang tidak dapat dipilih atau tidak memiliki titik penyisipan.
- Untuk memastikan bahwa teks dapat diakses sepenuhnya, kontrol yang mengimplementasikan ITextProvider juga harus mendukung antarmuka IValueProvider . IValueProvider melengkapi ITextProvider dengan menyediakan cara terprogram untuk mengubah teks. Ini juga menawarkan kompatibilitas yang lebih besar dengan aplikasi klien teknologi bantu, termasuk yang didasarkan pada teknologi warisan seperti Aksesibilitas Aktif Microsoft. Ketika kedua pola kontrol diimplementasikan, peristiwa TextChanged (UIA_Text_TextChangedEventId) dan peristiwa AutomationPropertyChanged (UIA_AutomationPropertyChangedEventId) setara untuk properti Nilai (UIA_ValueValuePropertyId). Kedua peristiwa harus didukung.
- Pola Kontrol teks hanya mendukung satu aliran teks dan satu viewport per kontrol. Jika aplikasi menawarkan beberapa tampilan dokumen di panel, setiap tampilan (kontrol) harus mendukung ITextProvider secara independen.
- Metode ITextProvider::GetSelection dapat mengembalikan satu rentang teks yang mewakili teks yang saat ini dipilih. Jika kontrol mendukung pemilihan beberapa rentang teks yang tidak berdekatan, metode GetSelection harus mengembalikan array yang berisi satu antarmuka ITextRangeProvider untuk setiap rentang teks yang dipilih.
- Pola kontrol Teks mewakili titik penyisipan sebagai rentang teks degenerasi (kosong). Metode ITextProvider::GetSelection harus mengembalikan rentang teks degenerasi saat titik penyisipan ada dan tidak ada teks yang dipilih. Untuk informasi selengkapnya, lihat Interoperabilitas dengan System Caret.
- Metode ITextProvider::GetVisibleRanges dapat mengembalikan rentang teks tunggal jika rentang teks yang berdekatan terlihat di viewport, atau dapat mengembalikan array rentang teks terputus-putus yang mewakili beberapa baris teks yang terlihat sebagian.
- Metode ITextProvider::RangeFromChild harus mengembalikan rentang degenerasi jika elemen anak tidak berisi teks. Karena objek yang disematkan dapat menyertakan teks, metode RangeFromChild mungkin tidak selalu mengembalikan rentang teks degenerasi. Untuk informasi selengkapnya, lihat Cara Automasi UI Mengekspos Objek Tersemat.
- Metode ITextProvider::RangeFromPoint melakukan pengujian hit di area dokumen menggunakan koordinat layar yang ditentukan. Rentang teks yang dihasilkan harus konsisten dengan titik penyisipan atau pilihan yang akan dihasilkan dari mengklik lokasi pada koordinat layar yang ditentukan. Misalnya, jika gambar berada di koordinat layar yang ditentukan, rentang teks yang dihasilkan harus sama dengan rentang teks yang akan diperoleh metode ITextProvider::RangeFromChild untuk gambar. Demikian pula, jika aplikasi klien meminta rentang teks untuk lokasi di tengah sisipan sistem (titik penyisipan), rentang teks yang dihasilkan harus sama dengan lokasi caret sistem.
- Properti ITextProvider::D ocumentRange harus selalu menyediakan rentang teks yang menyertakan semua teks yang didukung oleh implementasi ITextProvider yang sesuai.
- Peristiwa UIA_Text_TextChangedEventId harus dimunculkan setelah perubahan teks terjadi, meskipun perubahan tidak terlihat di viewport. Misalnya, penyedia harus menaikkan peristiwa bahkan jika pengguna menempelkan teks yang sama persis di atas teks yang dipilih.
- UIA_Text_TextSelectionChangedEventId harus dinaikkan setiap kali pilihan teks berubah, atau setiap kali titik penyisipan (tanda sisipan) berpindah di antara teks.
Saat menerapkan pola kontrol TextRange , perhatikan panduan dan konvensi berikut:
- Semua metode pola kontrol TextRange harus melakukan operasi teks terlepas dari status visibilitas teks. Visibilitas rentang teks selalu dapat ditentukan dengan mengkueri atribut teks IsHidden (UIA_IsHiddenAttributeId).
- Jika memungkinkan, penyedia harus memastikan bahwa setiap perubahan teks, seperti penghapusan, penyisipan, dan pemindahan, tercermin dalam objek rentang teks terkait (instans antarmuka ITextRangeProvider ) dan menaikkan peristiwa UIA_Text_TextChangedEventId . Klien dapat menggunakan peristiwa sebagai petunjuk untuk mengonfirmasi perubahan editorial yang dilakukan pada teks kontrol.
- Semua objek rentang teks yang digunakan oleh metode ITextRangeProvider::Compare, CompareEndpoints, dan MoveEndpointByRange harus berupa serekan dari implementasi pola kontrol Teks yang sama.
- Meskipun tidak diperlukan, nilai pRetVal yang diambil oleh metode ITextRangeProvider::CompareEndpoints dapat menunjukkan jarak, dalam karakter (TextUnit_Character), di antara dua titik akhir. Namun, aplikasi klien tidak boleh bergantung pada akurasi pRetVal di luar nilai positif atau negatifnya.
- Metode ITextRangeProvider::ExpandToEnclosingUnit, Move, dan MoveEndpointByUnit memerlukan pertimbangan yang cermat dari unit teks yang ditentukan. Untuk informasi selengkapnya, lihat Memanipulasi TextRange menurut Unit Teks.
- Untuk persyaratan implementasi yang terkait dengan metode ITextRangeProvider::Select, AddToSelection, dan RemoveFromSelection , lihat Memilih Teks dalam Rentang Teks.
- Metode ITextRangeProvider::FindText dan FindAttribute mencari maju atau mundur untuk satu string teks atau atribut teks yang cocok. Mereka harus mengembalikan NULL jika tidak ada kecocokan yang ditemukan.
- Metode ITextRangeProvider::GetAttributeValue harus mengembalikan alamat yang diperoleh dari fungsi UiaGetReservedMixedAttributeValue atau UiaGetReservedNotSupportedValue jika atribut terkait bervariasi dalam rentang, atau jika atribut tidak didukung oleh kontrol teks. Spesifikasi pola kontrol TextRange tidak memungkinkan penambahan pengidentifikasi atribut teks baru atau mengubah bagaimana atribut yang ada ditentukan.
- Jika memungkinkan, metode ITextRangeProvider::GetBoundingRectangles harus mengembalikan array yang berisi satu persegi panjang pembatas untuk setiap baris teks yang terlihat sepenuhnya atau sebagian dalam rentang teks. Jika ini tidak memungkinkan, penyedia dapat mengembalikan array yang berisi persegi panjang pembatas hanya dari garis yang terlihat sepenuhnya; namun, ini membatasi kemampuan aplikasi klien untuk secara akurat menggambarkan bagaimana teks disajikan di layar.
- Metode ITextRangeProvider::GetChildren harus mengembalikan semua elemen turunan yang disematkan dalam rentang teks, tetapi tidak perlu mengembalikan anak apa pun dari elemen anak. Misalnya, jika rentang teks berisi tabel yang memiliki sejumlah sel anak, metode GetChildren hanya dapat mengembalikan elemen tabel dan bukan elemen sel. Untuk alasan performa atau arsitektur, penyedia mungkin tidak dapat mengekspos semua objek tersemat yang dihosting dalam dokumen di pohon otomatisasi. Dalam hal ini, penyedia setidaknya harus mendukung enumerasi objek anak melalui metode GetChildren dan, sebagai opsi, mendukung pola kontrol VirtualizedItem untuk dukungan de-virtualisasi.
- Metode ITextRangeProvider::GetEnclosingElement biasanya mengembalikan penyedia teks yang menyediakan rentang teks. Namun, jika penyedia teks mendukung objek anak seperti tabel atau hyperlink, elemen yang diapit bisa menjadi turunan dari penyedia teks. Elemen yang dikembalikan oleh GetEnclosingElement harus menjadi elemen yang paling dekat dengan rentang teks yang diberikan. Misalnya, jika rentang teks berada dalam sel tabel, GetEnclosingElement harus mengembalikan sel yang berisi alih-alih elemen tabel.
- Metode ITextRangeProvider::GetText harus mengembalikan teks biasa dalam rentang. Untuk informasi selengkapnya, lihat Memperoleh Teks dari Rentang Teks.
- Memanggil ITextRangeProvider::ScrollIntoView harus meratakan teks dalam viewport kontrol teks seperti yang ditentukan oleh parameter alignToTop . Meskipun tidak ada persyaratan dalam hal perataan horizontal, rentang teks harus terlihat baik secara horizontal maupun vertikal. Saat mengevaluasi parameter alignToTop , penyedia harus mempertimbangkan orientasi kontrol teks dan arah alur teks. Misalnya, jika alignToToptrue untuk kontrol teks berorientasi vertikal yang berisi teks yang mengalir dari kanan ke kiri, penyedia harus meratakan rentang teks dengan sisi kanan viewport.
- Saat menelusuri dokumen dengan TextUnit_Line, jika rentang teks memasukkan tabel yang disematkan, setiap baris teks dalam sel harus diperlakukan sebagai baris.
Anggota yang Diperlukan untuk ITextProvider
Properti dan metode berikut diperlukan untuk mengimplementasikan antarmuka ITextProvider .
| Anggota yang diperlukan | Jenis anggota | Catatan |
|---|---|---|
| DocumentRange | Properti | Tidak ada |
| SupportedTextSelection | Properti | Tidak ada |
| GetSelection | Metode | Tidak ada |
| GetVisibleRanges | Metode | Tidak ada |
| RangeFromChild | Metode | Tidak ada |
| RangeFromPoint | Metode | Tidak ada |
| UIA_Text_TextChangedEventId | Kejadian | Tidak ada |
| UIA_Text_TextSelectionChangedEventId | Kejadian | Tidak ada |
Properti dan metode tambahan berikut diperlukan untuk mengimplementasikan antarmuka ITextProvider2 .
| Anggota yang diperlukan | Jenis anggota | Catatan |
|---|---|---|
| GetCaretRange | Metode | Tidak ada |
| RangeFromAnnotation | Metode | Tidak ada |
Anggota yang Diperlukan untuk ITextRangeProvider
Properti dan metode berikut diperlukan untuk mengimplementasikan antarmuka ITextRangeProvider .
| Anggota yang diperlukan | Jenis anggota | Catatan |
|---|---|---|
| TambahkanToSelection | Metode | Tidak ada |
| Kloning | Metode | Tidak ada |
| Bandingkan | Metode | Tidak ada |
| CompareEndpoints | Metode | Tidak ada |
| ExpandToEnclosingUnit | Metode | Tidak ada |
| FindAttribute | Metode | Tidak ada |
| FindText | Metode | Tidak ada |
| GetAttributeValue | Metode | Tidak ada |
| GetBoundingRectangles | Metode | Tidak ada |
| GetChildren | Metode | Tidak ada |
| GetEnclosingElement | Metode | Tidak ada |
| GetText | Metode | Tidak ada |
| Bergerak | Metode | Tidak ada |
| MoveEndpointByUnit | Metode | Tidak ada |
| MoveEndpointByRange | Metode | Tidak ada |
| Pilih | Metode | Tidak ada |
| ScrollIntoView | Metode | Tidak ada |
Properti dan metode tambahan berikut diperlukan untuk mengimplementasikan antarmuka ITextRangeProvider2 .
| Anggota yang diperlukan | Jenis anggota | Catatan |
|---|---|---|
| TampilkanContextMenu | Metode | Lihat bagian "Mengimplementasikan ShowContextMenu" |
Pola kontrol TextRange tidak memiliki peristiwa terkait.
Rentang Teks Pendukung
Bagian ini menjelaskan bagaimana penyedia harus menerapkan berbagai metode antarmuka ITextRangeProvider dan ITextRangeProvider2 untuk mendukung pola kontrol TextRange .
Memanipulasi Rentang Teks menurut Unit Teks
Antarmuka ITextRangeProvider menyediakan beberapa metode untuk memanipulasi dan menavigasi rentang teks dalam kontrol berbasis teks. Metode ITextRangeProvider::Move, MoveEndpointByUnit, dan ExpandToEnclosingUnit memindahkan rentang teks atau salah satu titik akhirnya oleh unit teks yang ditentukan, seperti karakter, kata, paragraf, dan sebagainya. Untuk informasi selengkapnya, lihat Unit Teks Automasi UI.
Terlepas dari namanya, metode ITextRangeProvider::ExpandToEnclosingUnit tidak selalu memperluas rentang teks. Sebaliknya, ia "menormalkan" rentang teks dengan memindahkan titik akhir sehingga rentang mencakup unit teks yang ditentukan. Rentang diperluas jika lebih kecil dari unit yang ditentukan, atau dipersingkat jika lebih panjang dari unit yang ditentukan. Sangat penting bahwa metode ExpandToEnclosingUnit selalu menormalkan rentang teks secara konsisten; jika tidak, aspek lain dari manipulasi rentang teks berdasarkan unit teks tidak akan dapat diprediksi. Diagram berikut menunjukkan bagaimana ExpandToEnclosingUnit menormalkan rentang teks dengan memindahkan titik akhir rentang.
Jika rentang teks dimulai di awal unit teks dan berakhir di awal, atau sebelumnya, batas unit teks berikutnya, titik akhir dipindahkan ke batas unit teks berikutnya (lihat 1 dan 2 di diagram sebelumnya).
Jika rentang teks dimulai di awal unit teks dan berakhir pada, atau setelahnya, batas unit berikutnya, titik akhir akan tetap ada atau dipindahkan mundur ke batas unit berikutnya setelah titik akhir awal (lihat 3 dan 4 dalam ilustrasi sebelumnya). Jika ada lebih dari satu batas unit teks antara titik akhir awal dan akhir, titik akhir dipindahkan mundur ke batas unit berikutnya setelah titik akhir awal, menghasilkan rentang teks yang panjangnya satu unit teks.
Jika rentang teks dimulai di tengah unit teks, titik akhir awal dipindahkan mundur ke awal unit teks, dan titik akhir dipindahkan ke depan atau mundur, jika perlu, ke batas unit berikutnya setelah titik akhir awal (lihat 5 hingga 8 dalam diagram sebelumnya).
Ketika metode ITextRangeProvider::Move dipanggil, penyedia menormalkan rentang teks oleh unit teks yang ditentukan, menggunakan logika normalisasi yang sama dengan metode ExpandToEnclosingUnit . Kemudian, penyedia memindahkan rentang mundur atau maju dengan jumlah unit teks yang ditentukan. Saat memindahkan rentang, penyedia harus mengabaikan batas objek yang disematkan dalam teks. (Namun, batas unit itu sendiri dapat dipengaruhi oleh keberadaan objek yang disematkan). Diagram berikut menunjukkan bagaimana metode Pindahkan memindahkan rentang teks, unit menurut unit, di seluruh objek yang disematkan dan batas unit teks.
Metode ITextRangeProvider::MoveEndpointByUnit memindahkan salah satu titik akhir ke depan atau mundur oleh unit teks tertentu, seperti yang ditunjukkan oleh ilustrasi berikut.
Metode ITextRangeProvider::MoveEndpointByRange memungkinkan aplikasi klien untuk mengatur satu titik akhir rentang teks ke lokasi yang sama dengan titik akhir rentang teks kedua yang ditentukan.
Memilih Teks dalam Rentang Teks
Antarmuka ITextRangeProvider mencakup beberapa metode untuk mengontrol pemilihan teks dalam kontrol berbasis teks.
Metode ITextRangeProvider::Select harus memilih teks yang sesuai dengan rentang teks, dan menghapus pilihan sebelumnya, jika ada, dari kontrol teks. Jika Pilih dipanggil pada rentang teks degenerasi, penyedia harus memindahkan titik penyisipan ke lokasi rentang teks tanpa memilih teks apa pun.
Jika kontrol mendukung pilihan beberapa, rentang teks terpisah, metode ITextRangeProvider::AddToSelection dan RemoveFromSelection menambahkan rentang teks ke, dan menghapusnya dari, kumpulan rentang teks yang dipilih. Jika kontrol hanya mendukung satu rentang teks yang dipilih pada satu waktu, tetapi operasi pemilihan akan menghasilkan pemilihan beberapa rentang teks terputus-putus, penyedia harus mengembalikan kesalahan E_INVALIDOPERATION , atau harus memperluas atau memotong pilihan saat ini. Properti ITextProvider::SupportedTextSelection harus menunjukkan apakah kontrol mendukung pemilihan satu atau beberapa rentang teks, atau tidak sama sekali.
Jika kontrol berbasis teks mendukung penyisipan teks, memanggil ITextRangeProvider::AddToSelection atau RemoveFromSelection pada rentang teks degenerasi dalam kontrol harus memindahkan titik penyisipan tetapi tidak boleh memilih teks apa pun.
Memperoleh Teks dari Rentang Teks
Metode ITextRangeProvider::GetText harus mengembalikan teks biasa dari rentang teks. Teks biasa harus menyertakan semua karakter kontrol yang ditemukan dalam teks sumber, seperti pengembalian pengangkutan dan tanda kiri-ke-kanan (LRM) Unicode. Teks biasa tidak boleh menyertakan tag markup apa pun seperti HTML yang mungkin ada dalam teks sumber. Selain itu, kode escape apa pun dalam teks sumber harus dikonversi ke teks biasa yang setara. Misalnya, " " harus dikonversi menjadi karakter spasi sederhana.
Jika objek yang disematkan mencakup rentang teks, teks biasa harus menyertakan teks dalam objek, tetapi bukan teks alternatif (properti nama objek yang disematkan) karena mungkin tidak konsisten dengan teks dalam deskriptif. Untuk informasi selengkapnya, lihat Cara Automasi UI Mengekspos Objek Tersemat.
Menerapkan ShowContextMenu
ITextRangeProvider2::ShowContextMenu harus selalu menampilkan menu konteks di titik akhir awal rentang. Ini harus setara dengan apa yang akan terjadi jika pengguna menekan tombol menu konteks atau SHIFT + F10 dengan titik penyisipan di awal rentang.
Jika menampilkan menu konteks biasanya akan mengakibatkan titik penyisipan berpindah ke lokasi tertentu, maka itu harus melakukannya untuk secara terprogram memanggil ShowContextMenu untuk dukungan Otomatisasi UI juga.
Interoperabilitas dengan System Caret
Mendukung titik penyisipan dengan benar sangat penting bagi banyak aplikasi klien, termasuk yang tidak didasarkan pada Automasi UI. Dalam pola Kontrol teks , titik penyisipan diwakili oleh rentang teks degenerasi (kosong) pada posisi sisipan sistem. Saat titik penyisipan bergerak, kontrol harus menaikkan peristiwa TextSelectionChanged (UIA_Text_TextSelectionChangedEventId). Beberapa aplikasi klien bergantung pada peristiwa ini untuk memantau lokasi titik penyisipan, dan untuk melacak pemilihan teks.
Ketika kontrol berisi teks yang dipilih, desain pola kontrol Teks saat ini tidak menyediakan cara untuk secara langsung mengaitkan lokasi titik penyisipan dengan rentang teks tertentu. Penyedia harus melacak pemilihan teks dan mengatur lokasi titik penyisipan dengan tepat. Karena memilih teks biasanya dilakukan dengan memindahkan titik penyisipan sambil menahan tombol SHIFT atau CTRL, atau keduanya, penyedia dapat melacak pilihan teks dengan memeriksa status kunci ini setiap kali pilihan berubah.
Karena kerangka kerja aksesibilitas menyediakan dukungan bawaan untuk caret sistem tetapi tidak untuk caret kustom, kontrol berbasis teks harus menggunakan caret sistem jika memungkinkan. Kontrol yang menggunakan caret kustom dapat memastikan bahwa caret dapat diakses dengan membuat caret sistem yang memiliki dimensi yang sama dengan caret kustom, dan memposisikan caret sistem pada lokasi yang sama di UI kontrol sebagai caret kustom—yaitu, pada titik penyisipan. Sebagai alternatif, kontrol yang menggunakan caret kustom dapat mengimplementasikan penyedia Aksesibilitas Aktif Microsoft untuk OBJID_CARET untuk memberikan informasi aksesibilitas secara langsung untuk caret kustom Anda.
Untuk informasi selengkapnya tentang caret sistem, lihat Caret.
Untuk menguji apakah kontrol Anda mengekspos lokasi caret sistem dengan benar, gunakan alat Inspect and Accessible Event Watcher .
Koordinat layar pusat bitmap caret sistem harus selalu cocok dengan lokasi titik penyisipan. Dengan begitu, klien dapat menggunakan koordinat layar caret dalam panggilan ke ITextProvider::RangeFromPoint untuk mengambil rentang teks yang secara akurat mewakili lokasi titik penyisipan.
Topik terkait
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk