Input teks kustom

API teks inti di namespace Windows.UI.Text.Core memungkinkan aplikasi Windows untuk menerima input teks dari layanan teks apa pun yang didukung di perangkat Windows. API mirip dengan TEXT Services Framework API karena aplikasi tidak diharuskan untuk memiliki pengetahuan terperinci tentang layanan teks. Ini memungkinkan aplikasi untuk menerima teks dalam bahasa apa pun dan dari jenis input apa pun, seperti keyboard, ucapan, atau pena.

API Penting: Windows.UI.Text.Core, CoreTextEditContext

Mengapa menggunakan API teks inti?

Untuk banyak aplikasi, kontrol kotak teks XAML atau HTML cukup untuk input dan pengeditan teks. Namun, jika aplikasi Anda menangani skenario teks yang kompleks, seperti aplikasi pemrosesan kata, Anda mungkin memerlukan fleksibilitas kontrol pengeditan teks kustom. Anda dapat menggunakan API keyboard CoreWindow untuk membuat kontrol edit teks, tetapi ini tidak menyediakan cara untuk menerima input teks berbasis komposisi, yang diperlukan untuk mendukung bahasa Asia Timur.

Sebagai gantinya , gunakan API Windows.UI.Text.Core saat Anda perlu membuat kontrol pengeditan teks kustom. API ini dirancang untuk memberi Anda banyak fleksibilitas dalam memproses input teks, dalam bahasa apa pun, dan memungkinkan Anda memberikan pengalaman teks yang paling cocok untuk aplikasi Anda. Kontrol input dan edit teks yang dibangun dengan API teks inti dapat menerima input teks dari semua metode input teks yang ada di perangkat Windows, dari Editor Metode Input (IMEs) berbasis Kerangka Kerja Layanan Teks dan tulisan tangan pada PC ke keyboard WordFlow (yang menyediakan koreksi otomatis, prediksi, dan dikte) pada perangkat seluler.

Sistem

Berikut ini adalah representasi sederhana dari sistem input teks.

• "Aplikasi" mewakili aplikasi Windows yang menghosting kontrol edit kustom yang dibangun menggunakan API teks inti.
• API Windows.UI.Text.Core memfasilitasi komunikasi dengan layanan teks melalui Windows. Komunikasi antara kontrol edit teks dan layanan teks ditangani terutama melalui objek CoreTextEditContext yang menyediakan metode dan peristiwa untuk memfasilitasi komunikasi.

Rentang teks dan pilihan

Kontrol edit menyediakan ruang untuk entri teks dan pengguna mengharapkan untuk mengedit teks di mana saja di ruang ini. Di sini, kami menjelaskan sistem pemosisian teks yang digunakan oleh API teks inti dan bagaimana rentang dan pilihan diwakili dalam sistem ini.

Posisi caret aplikasi

Rentang teks yang digunakan dengan API teks inti dinyatakan dalam hal posisi tanda sisipan. "Posisi Perawatan Aplikasi (ACP)" adalah angka berbasis nol yang menunjukkan jumlah karakter dari awal aliran teks segera sebelum tanda sisipan, seperti yang ditunjukkan di sini.

Rentang teks dan pilihan

Rentang teks dan pilihan diwakili oleh struktur CoreTextRange yang berisi dua bidang:

Bidang	Jenis data	Deskripsi
StartCaretPosition	Angka [JavaScript] | System.Int32 [.NET] | int32 [C++]	Posisi awal rentang adalah ACP segera sebelum karakter pertama.
EndCaretPosition	Angka [JavaScript] | System.Int32 [.NET] | int32 [C++]	Posisi akhir rentang adalah ACP segera setelah karakter terakhir.

 

Misalnya, dalam rentang teks yang ditunjukkan sebelumnya, rentang [0, 5] menentukan kata "Hello". StartCaretPosition harus selalu kurang dari atau sama dengan EndCaretPosition. Rentang [5, 0] tidak valid.

Titik penyisipan

Posisi caret saat ini, sering disebut sebagai titik penyisipan, diwakili dengan mengatur StartCaretPosition agar sama dengan EndCaretPosition.

Pilihan yang tidak berdamai

Beberapa kontrol edit mendukung pilihan yang tidak berdamai. Misalnya, Microsoft aplikasi Office s mendukung beberapa pilihan arbitrer, dan banyak editor kode sumber mendukung pemilihan kolom. Namun, API teks inti tidak mendukung pilihan yang tidak bersebelahan. Kontrol edit hanya boleh melaporkan satu pilihan yang bersebelahan, paling sering sub-rentang aktif dari pilihan yang tidak bersebelahan.

Misalnya, gambar berikut menunjukkan aliran teks dengan dua pilihan yang tidak berdampingan: [0, 1] dan [6, 11] yang kontrol editnya hanya boleh melaporkan satu (baik [0, 1] atau [6, 11]).

Mengerjakan teks

Kelas CoreTextEditContext memungkinkan aliran teks antara Windows dan mengedit kontrol melalui peristiwa TextUpdating, peristiwa TextRequested, dan metode NotifyTextChanged.

Kontrol edit Anda menerima teks melalui peristiwa TextUpdating yang dihasilkan saat pengguna berinteraksi dengan metode input teks seperti keyboard, ucapan, atau IMEs.

Saat Anda mengubah teks dalam kontrol edit, misalnya, dengan menempelkan teks ke kontrol, Anda perlu memberi tahu Windows dengan memanggil NotifyTextChanged.

Jika layanan teks memerlukan teks baru, maka peristiwa TextRequested akan dinaikkan. Anda harus menyediakan teks baru di penanganan aktivitas TextRequested .

Menerima pembaruan teks

Kontrol edit Anda biasanya harus menerima permintaan pembaruan teks karena mewakili teks yang ingin dimasukkan pengguna. Di penanganan aktivitas TextUpdating , tindakan ini diharapkan dari kontrol edit Anda:

1. Sisipkan teks yang ditentukan dalam CoreTextTextUpdatingEventArgs.Text dalam posisi yang ditentukan dalam CoreTextTextUpdatingEventArgs.Range.
2. Tempatkan pilihan pada posisi yang ditentukan dalam CoreTextTextUpdatingEventArgs.NewSelection.
3. Beri tahu sistem bahwa pembaruan berhasil dengan mengatur CoreTextTextUpdatingEventArgs.Result ke CoreTextTextUpdatingResult.Succeeded.

Misalnya, ini adalah status kontrol edit sebelum pengguna mengetikan "d". Titik penyisipan berada di [10, 10].

Saat pengguna mengetik "d", peristiwa TextUpdating dinaikkan dengan data CoreTextTextUpdatingEventArgs berikut:

• Rentang = [10, 10]
• Teks = "d"
• NewSelection = [11, 11]

Di kontrol edit Anda, terapkan perubahan yang ditentukan dan atur Hasil ke Berhasil. Berikut adalah status kontrol setelah perubahan diterapkan.

Menolak pembaruan teks

Terkadang, Anda tidak dapat menerapkan pembaruan teks karena rentang yang diminta berada di area kontrol edit yang tidak boleh diubah. Dalam hal ini, Anda tidak boleh menerapkan perubahan apa pun. Sebagai gantinya, beri tahu sistem bahwa pembaruan gagal dengan mengatur CoreTextTextUpdatingEventArgs.Result ke CoreTextTextUpdatingResult.Failed.

Misalnya, pertimbangkan kontrol edit yang hanya menerima alamat email. Spasi harus ditolak karena alamat email tidak boleh berisi spasi, jadi ketika peristiwa TextUpdating dinaikkan untuk kunci spasi, Anda cukup mengatur Hasil ke Gagal dalam kontrol edit Anda.

Memberi tahu perubahan teks

Terkadang, kontrol edit Anda membuat perubahan pada teks seperti saat teks ditempelkan atau dikoreksi secara otomatis. Dalam kasus ini, Anda harus memberi tahu layanan teks tentang perubahan ini dengan memanggil metode NotifyTextChanged.

Misalnya, ini adalah status kontrol edit sebelum pengguna menempelkan "Dunia". Titik penyisipan berada di [6, 6].

Pengguna melakukan tindakan tempel dan kontrol edit setelah perubahan diterapkan:

Ketika ini terjadi, Anda harus memanggil NotifyTextChanged dengan argumen ini:

• modifiedRange = [6, 6]
• newLength = 5
• newSelection = [11, 11]

Satu atau beberapa peristiwa TextRequested akan mengikuti, yang Anda tangani untuk memperbarui teks yang bekerja dengan layanan teks.

Mengesampingkan pembaruan teks

Di kontrol edit, Anda mungkin ingin mengambil alih pembaruan teks untuk menyediakan fitur koreksi otomatis.

Misalnya, pertimbangkan kontrol edit yang menyediakan fitur koreksi yang memformalkan kontraksi. Ini adalah status kontrol edit sebelum pengguna mengetikan kunci spasi untuk memicu koreksi. Titik penyisipan berada di [3, 3].

Pengguna menekan tombol spasi dan peristiwa TextUpdating yang sesuai dinaikkan. Kontrol edit menerima pembaruan teks. Ini adalah status kontrol edit untuk sesaat sebelum koreksi selesai. Titik penyisipan berada di [4, 4].

Di luar penanganan aktivitas TextUpdating, kontrol edit melakukan koreksi berikut. Ini adalah status kontrol edit setelah koreksi selesai. Titik penyisipan berada di [5, 5].

Ketika ini terjadi, Anda harus memanggil NotifyTextChanged dengan argumen ini:

• modifiedRange = [1, 2]
• newLength = 2
• newSelection = [5, 5]

Satu atau beberapa peristiwa TextRequested akan mengikuti, yang Anda tangani untuk memperbarui teks yang bekerja dengan layanan teks.

Menyediakan teks yang diminta

Penting bagi layanan teks untuk memiliki teks yang benar untuk menyediakan fitur seperti koreksi otomatis atau prediksi, terutama untuk teks yang sudah ada di kontrol edit, dari memuat dokumen, misalnya, atau teks yang disisipkan oleh kontrol edit seperti yang dijelaskan di bagian sebelumnya. Oleh karena itu, setiap kali peristiwa TextRequested dinaikkan , Anda harus menyediakan teks yang saat ini berada dalam kontrol edit Anda untuk rentang yang ditentukan.

Akan ada kalanya Rentang di CoreTextTextRequest menentukan rentang yang tidak dapat diakomodasi oleh kontrol edit Anda apa adanya. Misalnya, Rentang lebih besar dari ukuran kontrol edit pada saat peristiwa TextRequested, atau akhir Rentang berada di luar batas. Dalam kasus ini, Anda harus mengembalikan rentang apa pun yang masuk akal, yang biasanya merupakan subset dari rentang yang diminta.

Artikel terkait

Sampel

• Sampel Kontrol Edit Kustom

Sampel arsip

• Sampel pengeditan teks XAML