Pola Kontrol Anotasi
Menjelaskan panduan dan konvensi untuk menerapkan IAnnotationProvider, termasuk informasi tentang properti dan metode. Pola kontrol Anotasi digunakan untuk mengekspos properti anotasi dalam dokumen.
Salah satu contohnya adalah balon komentar yang berada di margin dokumen dan tersambung ke beberapa teks dokumen atau sel lembar bentang.
Ilustrasi berikut menunjukkan contoh anotasi. Untuk contoh kontrol yang menerapkan pola kontrol ini, lihat Jenis Kontrol dan Pola Kontrol yang Didukung.
Topik ini berisi bagian berikut.
Panduan dan Konvensi Implementasi
Saat menerapkan pola kontrol Anotasi , perhatikan panduan dan konvensi berikut:
- Ada banyak jenis anotasi yang berbeda. File header UIAutomationClient.h menentukan sekumpulan nilai konstanta bernama yang mengidentifikasi jenis anotasi yang didukung Microsoft UI Automation. Untuk informasi selengkapnya, lihat Pengidentifikasi Jenis Anotasi.
- Jika Anda menggunakan AnnotationType_Unknown, Anda harus menerapkan properti IAnnotationProvider::AnnotationTypeName untuk memungkinkan klien menemukan nama jenis anotasi. Anda tidak perlu menerapkan AnnotationTypeName untuk jenis anotasi standar karena Automasi UI menyediakan nama default, tetapi Anda dapat menerapkannya jika Anda perlu mengganti nama default.
- Properti IAnnotationProvider::Author bersifat opsional.
- Properti IAnnotationProvider::D ateTime bersifat opsional.
- Properti IAnnotationProvider::Target diperlukan karena menautkan anotasi ke elemen UI, memungkinkan klien untuk menavigasi dari anotasi kembali ke elemen UI yang dirujuk oleh anotasi.
- Karena anotasi dapat mengambil banyak bentuk yang berbeda, antarmuka IAnnotationProvider tidak menentukan properti untuk menyimpan nilai atau teks anotasi. Anotasi sederhana harus mengekspos antarmuka IValueProvider , dan properti IValueProvider::Value harus mengembalikan nilai baca-saja yang menentukan teks anotasi. Anotasi yang lebih kaya harus mengekspos antarmuka ITextProvider untuk menyediakan teks yang lebih kaya kepada klien.
- Menavigasi dari elemen UI ke anotasi pada elemen tergantung pada jenis elemen yang diannotasikan, sebagai berikut:
- Untuk sel spreadsheet, terapkan metode ISpreadsheetItemProvider::GetAnnotationObjects untuk merujuk ke anotasi.
- Untuk konten tekstual, terapkan atribut teks AnnotationObjects pada antarmuka ITextRangeProvider untuk merujuk ke anotasi.
- Beberapa jenis anotasi tidak memerlukan implementasi penuh antarmuka IAnnotationProvider . Misalnya, indikator kesalahan ejaan sederhana dapat diwakili dengan meminta antarmuka ITextRangeProvider mengembalikan atribut teks AnnotationTypesAnnotationType_SpellingError, dan nilai null untuk atribut teks AnnotationObjects .
- Ini dapat berguna untuk mengimplementasikan antarmuka IAnnotationProvider pada elemen UI yang tidak terlihat. Misalnya, Anda dapat membuat elemen Automation UI yang tidak terlihat yang mengimplementasikan IAnnotationProvider untuk memberikan informasi yang diperluas tentang kesalahan tata bahasa.
- Anotasi dalam kontrol berbasis teks bisa rumit jika kontrol berisi komentar yang tumpang tindih. Gunakan panduan berikut untuk menangani anotasi kompleks:
- Rentang teks tanpa anotasi harus mengembalikan array kosong untuk atribut teks AnnotationTypes dan array kosong untuk atribut teks AnnotationObjects .
- Rentang teks dengan satu anotasi harus mengembalikan array dari satu nilai bilangan bulat untuk atribut teks AnnotationTypes dan array satu antarmuka IRawElementProviderSimple untuk atribut teks AnnotationObjects .
- Rentang teks dengan beberapa anotasi harus mengembalikan array beberapa nilai bilangan bulat untuk atribut teks AnnotationTypes dan array jumlah antarmuka IRawElementProviderSimple yang cocok untuk atribut teks AnnotationObjects .
- Rentang teks dengan berbagai anotasi, seperti rentang dengan teks anotasi dan non-anotasi, harus mengembalikan properti ReservedMixedAttributeValue untuk AnnotationTypes dan AnnotationObjects. Klien yang menerima respons ini dapat membavisi rentang teks untuk menemukan di mana anotasi dimulai dan berakhir.
Anggota yang Diperlukan untuk IAnnotationProvider
Properti berikut diperlukan untuk mengimplementasikan antarmuka IAnnotationProvider .
| Anggota yang diperlukan | Jenis anggota | Catatan |
|---|---|---|
| AnotasiTypeId | Properti | Tidak ada. |
| AnnotationTypeName | Properti | Tidak ada. |
| Penulis | Properti | Tidak ada. |
| Datetime | Properti | Tidak ada. |
| Target | Properti | Tidak ada. |
Pola kontrol ini tidak memiliki peristiwa terkait.
Topik terkait