Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Topik ini menjelaskan cara menggunakan properti dan metode antarmuka IUIAutomationTextRange untuk mengakses dan memanipulasi konten tekstual kontrol berbasis teks.
Apa itu Rentang Teks?
Model objek teks Microsoft UI Automation didasarkan pada konsep rentang teks. Rentang teks adalah objek yang mengekspos antarmuka IUIAutomationTextRange , dan mewakili rentang teks yang berdekatan dalam kontrol berbasis teks. Setiap rentang teks memiliki titik akhir awal dan titik akhir, dan semua konten tekstual di antara kedua titik akhir dianggap sebagai bagian dari rentang. Rentang teks yang titik akhir awal dan titik akhirnya berada di lokasi yang sama disebut rentang teks degenerasi (atau kosong). Rentang teks degenerasi digunakan untuk menandai lokasi tertentu dalam teks kontrol, seperti lokasi titik penyisipan teks.
Memperoleh Objek Rentang Teks
Aplikasi klien memperoleh objek rentang teks dengan menggunakan properti dan metode antarmuka IUIAutomationTextPattern . Properti IUIAutomationTextRangePattern::D ocumentRange mengambil rentang teks yang mewakili seluruh konten tekstual kontrol berbasis teks, sementara metode lain memperoleh rentang teks yang mewakili beberapa bagian konten, seperti teks yang dipilih, teks yang terlihat, atau objek yang disematkan dalam teks.
Metode IUIAutomationTextRangePattern::GetVisibleRanges dan GetSelection dapat mengambil array objek rentang teks. Jika kontrol dikaburkan sebagian oleh jendela yang tumpang tindih atau objek lain, GetVisibleRanges mengembalikan array yang berisi objek rentang teks untuk setiap baris teks yang terlihat sebagian. Demikian pula, jika kontrol berbasis teks mendukung pilihan beberapa rentang teks yang terpisah, GetSelection mengembalikan array yang berisi objek rentang teks untuk setiap rentang yang dipilih.
Metode IUIAutomationTextRangePattern::RangeFromChild memungkinkan aplikasi klien untuk mengambil rentang teks yang mengapit objek yang disematkan dalam konten tekstual. Klien menentukan penunjuk antarmuka IUIAutomationElement dari objek yang disematkan, seperti gambar, tabel, atau hyperlink, dan metode mengembalikan rentang teks yang mengapit objek. Namun, jika objek yang disematkan tidak memiliki teks yang terkait dengannya, metode mengembalikan rentang teks degenerasi.
Aplikasi klien dapat menggunakan metode IUIAutomationTextRangePattern::RangeFromPoint untuk mengambil rentang teks yang terlihat atau objek tersemat yang terdekat dengan koordinat layar yang ditentukan.
Memilih Teks dalam Rentang Teks
Antarmuka IUIAutomationTextRange mencakup sejumlah metode yang memungkinkan aplikasi klien mengontrol pemilihan teks dalam kontrol berbasis teks.
Aplikasi klien dapat menggunakan metode IUIAutomationTextRange::Select untuk memilih teks yang sesuai dengan rentang teks, dan untuk menghapus pilihan sebelumnya, jika ada, dari kontrol teks. Memanggil Pilih dengan rentang teks degenerasi memindahkan titik penyisipan ke lokasi rentang teks tanpa memilih teks apa pun.
Jika kontrol mendukung pemilihan beberapa rentang teks terpisah, klien dapat menggunakan metode IUIAutomationTextRange::AddToSelection dan RemoveFromSelection untuk menambahkan rentang teks, 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, metode mengembalikan kesalahan E_INVALIDOPERATION , atau memperluas atau memotong pilihan saat ini. Aplikasi klien dapat menemukan apakah kontrol mendukung pemilihan satu atau beberapa rentang teks, atau tidak sama sekali, dengan memeriksa properti IUIAutomationTextPattern::SupportedTextSelection .
Jika kontrol berbasis teks mendukung penyisipan teks, memanggil IUIAutomationTextRange::AddToSelection atau RemoveFromSelection pada rentang teks degenerasi dalam kontrol akan memindahkan titik penyisipan tetapi tidak memilih teks apa pun.
Mengambil Teks dari Rentang Teks
Aplikasi klien dapat menggunakan metode IUIAutomationTextRange::GetText untuk mengambil teks biasa dari rentang teks. Teks biasa mencakup semua karakter kontrol yang ditemukan dalam teks sumber, seperti pengangkutan kembali dan tanda kiri-ke-kanan (LRM) Unicode. Teks biasa tidak menyertakan tag markup apa pun seperti HTML yang mungkin ada dalam teks sumber. Selain itu, setiap kode escape dalam teks sumber dikonversi ke teks biasa yang setara. Misalnya, " " dikonversi menjadi karakter spasi sederhana.
Jika objek yang disematkan mencakup rentang teks, teks biasa menyertakan teks dalam objek, tetapi bukan teks alternatif (properti nama objek yang disematkan). Untuk informasi selengkapnya, lihat Cara Automasi UI Mengekspos Objek Tersemat.
Metode IUIAutomationTextRange::FindText mencari rentang teks untuk string tertentu dan, jika ditemukan, mengembalikan rentang teks baru yang mencakup string.
Mengambil Atribut Teks dari Rentang Teks
Atribut teks menentukan gaya pemformatan teks dalam kontrol berbasis teks, dan menyertakan hal-hal seperti warna latar depan, gaya poin, ukuran font, dan sebagainya. Automasi UI mendukung sejumlah atribut teks, dan menentukan pengidentifikasi untuk setiap atribut yang didukung. Aplikasi klien dapat mengkueri rentang teks untuk nilai atribut teks tertentu dengan menentukan pengidentifikasi atribut dalam panggilan ke metode IUIAutomationTextRange::GetAttributeValue , bersama dengan penunjuk ke struktur VARIAN yang menerima nilai atribut. Untuk informasi terperinci tentang setiap atribut teks yang didukung Automation UI, lihat Pengidentifikasi Atribut Teks.
Nilai yang diambil oleh GetAttributeValue mewakili nilai atribut di seluruh rentang teks. Jika semua teks dalam rentang berbagi nilai yang sama untuk atribut yang ditentukan, nilai tersebut dikembalikan oleh GetAttributeValue. Namun, jika nilai atribut bervariasi di seluruh rentang teks, GetAttributeValue mengembalikan penunjuk IUnknown ke objek token statis yang disebut objek ReservedMixedAttribute . Untuk menemukan apakah nilai atribut bervariasi di seluruh rentang teks, aplikasi klien harus membandingkan hasil GetAttributeValue dengan objek ReservedMixedAttribute yang diambil dari properti IUIAutomation::ReservedMixedAttributeValue .
Kontrol berbasis teks tidak diperlukan untuk mendukung semua atribut teks Automation UI. Jika klien memanggil metode IUIAutomationTextRange::GetAttributeValue dan meneruskan pengidentifikasi atribut yang tidak didukung, metode mengembalikan pointer IUnknown ke objek token statis yang disebut objek ReservedNotSupported . Untuk menemukan apakah atribut tertentu didukung, aplikasi klien harus membandingkan hasil GetAttributeValue dengan objek ReservedNotSupported yang diambil dari properti IUIAutomation::ReservedNotSupportedValue .
Aplikasi klien dapat menggunakan metode IUIAutomationTextRange::FindAttribute untuk mencari rentang teks yang memiliki atribut teks tertentu. Jika ditemukan, metode mengembalikan rentang teks baru yang mencakup teks yang cocok. Perhatikan bahwa FindAttribute mengembalikan rentang teks untuk teks yang cocok meskipun teks tidak terlihat.
Mengambil Objek Tersemat dari Rentang Teks
Rentang teks bisa menyertakan objek yang disematkan seperti tabel, gambar, hyperlink, dan sebagainya. Aplikasi klien dapat mengambil koleksi semua objek yang disematkan dalam rentang dengan memanggil metode IUIAutomationTextRange::GetChildren . Objek yang disematkan yang tumpang tindih dengan rentang tetapi tidak sepenuhnya diapit olehnya juga disertakan dalam koleksi. Jika rentang tidak berisi objek yang disematkan, GetChildren mengambil koleksi kosong.
Meskipun tergantung pada penyedia kontrol berbasis teks, metode GetChildren biasanya tidak mengembalikan anak-anak dari elemen yang disematkan. Misalnya, jika rentang teks berisi tabel yang memiliki sejumlah sel anak, metode GetChildren biasanya hanya mengembalikan elemen tabel dan bukan elemen sel.
Untuk alasan performa atau arsitektur, GetChildren mungkin tidak dapat mengambil objek IUIAutomationElement untuk semua objek yang disematkan dalam rentang teks. Sebagai gantinya, penyedia mungkin mengembalikan koleksi yang menyertakan item virtual. Untuk informasi selengkapnya, lihat Bekerja dengan Item Virtual.
Memanipulasi Rentang Teks
Antarmuka IUIAutomationTextRange menyediakan beberapa metode untuk memanipulasi dan menavigasi rentang teks dalam kontrol berbasis teks. Metode IUIAutomationTextRange::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 ExpandToEnclosingUnit tidak selalu memperluas rentang teks. Sebaliknya, ia "menormalkan" rentang teks dengan memindahkan titik akhir sehingga rentang mencakup unit teks yang ditentukan dengan tepat. Rentang diperluas jika lebih kecil dari unit yang ditentukan, atau dipersingkat jika lebih panjang dari unit yang ditentukan. 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 dalam ilustrasi 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 ilustrasi sebelumnya).
Ketika metode IUIAutomationTextRange::Move dipanggil, penyedia menormalkan rentang teks oleh unit teks yang ditentukan. Kemudian, penyedia memindahkan rentang mundur atau maju dengan jumlah unit teks yang ditentukan. Saat memindahkan rentang, penyedia 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 IUIAutomationTextRange::MoveEndpointByUnit memindahkan salah satu titik akhir ke depan atau mundur oleh unit teks tertentu. Ilustrasi berikut ini memperlihatkan bagaimana titik akhir bergerak maju.
Metode IUIAutomationTextRange::MoveEndpointByRange memungkinkan aplikasi klien untuk mengatur satu titik akhir rentang teks ke lokasi yang sama dengan titik akhir yang ditentukan dari rentang teks kedua.
Menggulir Rentang Teks ke Dalam Tampilan
Metode IUIAutomationTextRange::ScrollIntoView menggulir rentang teks sehingga teks terlihat di viewport kontrol berbasis teks. Saat memanggil ScrollIntoView, klien dapat menentukan apakah teks harus diratakan dengan bagian atas atau bawah viewport.
Mengambil Elemen Penutup dari Rentang Teks
Aplikasi klien dapat menggunakan metode IUIAutomationTextRange::GetEnclosingElement untuk mengambil penunjuk antarmuka IUIAutomation dari elemen terdalam yang mencakup rentang teks. Elemen penutup biasanya adalah penyedia teks yang memasok rentang teks. Namun, jika penyedia teks mendukung elemen anak seperti tabel atau hyperlink, elemen yang diapit bisa menjadi turunan dari penyedia teks.
Membandingkan dan Mengkloning Rentang Teks
Antarmuka IUIAutomationTextRange mencakup dua metode untuk membandingkan rentang teks. Metode IUIAutomationTextRange::Compare membandingkan titik akhir awal dan akhir dari dua rentang teks dan mengembalikan TRUE jika kedua titik akhir sama. Metode IUIAutomationTextRange::CompareEndpoints membandingkan titik akhir awal atau akhir dari dua rentang. Nilai yang dikembalikan adalah nol jika titik akhir sama, atau nilai positif atau nilai negatif yang menunjukkan posisi relatif dari dua titik akhir.
Aplikasi klien dapat menggunakan metode IUIAutomationTextRange::Clone untuk membuat salinan rentang teks yang tepat. Rentang teks baru dapat dimanipulasi secara independen dari rentang teks asli.
Mengambil Anotasi
Rentang teks dapat menyertakan anotasi jika kontrol berbasis teks mendukungnya. Ada banyak jenis anotasi yang berbeda. File header UIAutomationClient.h menentukan sekumpulan nilai konstanta bernama yang mengidentifikasi jenis anotasi yang didukung Otomasi UI. Untuk informasi selengkapnya, lihat Pengidentifikasi Jenis Anotasi.
Beberapa jenis anotasi diwakili oleh elemen otomatisasi yang mendukung pola kontrol Anotasi (antarmuka IUIAutomationAnnotationPattern ). Jenis anotasi lainnya diekspos melalui pola kontrol TextRange . Misalnya, penyedia dapat mengekspos indikator kesalahan ejaan sederhana dengan meminta metode IUIAutomationTextRange::GetAttributeValue mengembalikan atribut teks AnnotationTypesAnnotationType_SpellingError, dan nilai null untuk atribut teks AnnotationObjects .
Mengambil Jenis Anotasi dari Rentang Teks
Anda dapat mengambil daftar jenis anotasi yang ada dalam rentang teks dengan menggunakan metode IUIAutomationTextRange::GetAttributeValue . Saat memanggil metode , tentukan ID atribut teks UIA_AnnotationTypesAttributeId dan penunjuk ke parameter jenis VARIAN. Saat metode kembali, parameter VARIAN berisi daftar pengidentifikasi jenis anotasi, satu untuk setiap jenis anotasi dalam rentang teks. Untuk informasi selengkapnya, lihat Pengidentifikasi Jenis Anotasi.
Mengambil Semua Anotasi dari Rentang Teks
Untuk mengambil anotasi dari rentang teks, panggil metode IUIAutomationTextRange::GetAttributeValue , menentukan ID atribut teks UIA_AnnotationObjectsAttributeId dan penunjuk ke parameter jenis VARIAN. Ketika metode kembali, parameter VARIAN berisi antarmuka IUIAutomationElementArray yang mewakili array elemen otomatisasi, satu untuk setiap anotasi dalam rentang teks. Properti IUIAutomationElementArray::Length menunjukkan jumlah elemen dalam array, dan metode IUIAutomationElementArray::GetElement mengambil antarmuka IUIAutomationElement untuk elemen tertentu.
Mengambil Informasi Tentang Anotasi Tertentu
Untuk mengambil informasi tentang anotasi tertentu, pertama-tama ambil antarmuka IUIAutomationElement untuk elemen anotasi seperti yang dijelaskan di bagian sebelumnya. Selanjutnya, ambil antarmuka IUIAutomationAnnotationPattern untuk anotasi dengan memanggil metode IUIAutomationElement::GetCurrentPatternAs dengan ID pola kontrol UIA_AnnotationPatternId, pengidentifikasi antarmuka IID_IUIAutomationAnnotationPattern, dan alamat variabel yang menerima penunjuk IUIAutomationAnnotation untuk anotasi. Kueri properti antarmuka IUIAutomationAnnotation untuk mengambil nama jenis anotasi dan ID jenis, nama penulis anotasi, tanggal dan waktu anotasi, dan antarmuka IUIAutomationElement untuk elemen yang sedang dianotasikan.
Mengambil Teks Target Anotasi
Biasanya, anotasi berlaku untuk beberapa subset teks dalam rentang teks. Setelah Anda mengambil antarmuka IUIAutomationElement untuk anotasi, Anda dapat meneruskan antarmuka ke metode IUIAutomationTextRange2::RangeFromAnnotation untuk mengambil rentang teks yang berisi teks yang merupakan target anotasi.
Mengambil Gaya Visual
Penyedia menerapkan pola kontrol Gaya untuk menjelaskan elemen UI yang memiliki gaya, warna isian, pola isian, atau bentuk tertentu. Ini sangat berguna ketika menjelaskan elemen dalam dokumen, yang sering memiliki gaya seperti itu. Gaya seperti ini sering membawa informasi yang berguna bagi pelanggan penyandang disabilitas; misalnya, gaya dapat menggambarkan string tertentu sebagai judul dokumen, atau objek diagram alur tertentu sebagai berlian atau lingkaran.
Anda dapat menggunakan metode IUIAutomationTextRange::GetAttributeValue untuk mengambil nama dan pengidentifikasi gaya visual yang digunakan dalam rentang teks. Gunakan atribut teks UIA_StyleNameAttributeId untuk mengambil nama gaya, dan UIA_StyleIdAttributeId untuk mengambil pengidentifikasi gaya.
Kontrol berbasis teks yang mendukung gaya visual dapat mengimplementasikan pola kontrol Gaya untuk memungkinkan klien mengakses informasi tentang gaya visual yang digunakan oleh kontrol. Klien mengakses pola kontrol Gaya melalui antarmuka IUIAutomationStylesPattern . Anda dapat mengambil antarmuka ini dengan memanggil metode IUIAutomationElement::GetCurrentPattern atau GetCurrentPatternAs , menentukan UIA_StylesPatternId sebagai pengidentifikasi pola kontrol.
Antarmuka IUIAutomationStylesPattern mencakup properti dan metode yang menyediakan informasi berikut tentang gaya visual:
- Nama gaya visual, seperti "Normal" atau "Judul 1".
- Pengidentifikasi gaya visual. Untuk informasi selengkapnya, lihat Pengidentifikasi Gaya.
- Warna yang digunakan untuk mengisi kontrol berbasis teks.
- Warna pola yang digunakan untuk mengisi kontrol berbasis teks.
- Bentuk kontrol berbasis teks.
- Properti yang diperluas; yaitu, daftar nama dan nilai gaya khusus kontrol.
Memanggil Menu Konteks Dari Rentang Teks
Dimulai dengan Windows 8.1, rentang teks dapat mendukung antarmuka IUIAutomationTextRange2. Antarmuka ini mendukung metode ShowContextMenu . Anda dapat memanggil metode ini untuk memanggil menu konteks apa pun yang terkait dengan rentang teks. Skenario untuk ini adalah koreksi otomatis rentang teks atau pilihan kandidat IME. Dalam kasus ini, menu konteks muncul yang mendukung interaksi pengguna.
Topik terkait