Editor teks kustom adalah tampilan yang bukan merupakan
komponen EditText
atau
widget teks WebView
, tetapi
tetap mendukung input teks dengan menerapkan callback
onCreateInputConnection()
yang dipanggil saat tampilan difokuskan dan sistem meminta
InputConnection
untuk tampilan.
Panggilan ke
onCheckIsTextEditor()
dari editor teks kustom akan menampilkan true
.
Dukung tulisan tangan stilus di editor teks kustom
Android 14 (level API 34) dan yang lebih tinggi mendukung input stilus dalam komponen entri teks Android standar secara default (lihat Input stilus di kolom teks). Namun, kolom entri teks kustom (atau editor) memerlukan pengembangan tambahan.
Untuk membuat editor teks kustom, lakukan hal berikut:
- Aktifkan inisiasi tulis tangan
- Mendeklarasikan dukungan tulis tangan
- Mendukung gestur tulis tangan (pilih, hapus, masukkan, dan sebagainya)
- Memberikan lokasi kursor dan data posisi lainnya ke IME
- Tampilkan ikon kursor tulisan tangan stilus
Aktifkan inisiasi tulis tangan
Jika tampilan hanya terdiri dari satu editor teks, sistem tampilan dapat secara otomatis memulai tulisan tangan stilus untuk tampilan tersebut. Jika tidak, tampilan harus menerapkan logika inisiasi tulisan tangannya sendiri.
Inisiasi tulisan tangan otomatis
Jika tampilan menampilkan satu editor teks dan tidak ada konten lain, tampilan tersebut dapat ikut serta dalam inisiasi tulisan tangan otomatis sistem tampilan dengan memanggil
setAutoHandwritingEnabled(true)
.
Dengan mengaktifkan tulis tangan otomatis, gerakan stilus yang dimulai di mana saja dalam batas tulisan tangan tampilan akan otomatis memulai mode tulis tangan. Editor metode input (IME) menerima peristiwa gerakan stilus dan melakukan commit teks yang dikenali.
![Kolom input dengan persegi panjang di sekitarnya yang menunjukkan batas untuk mendeteksi peristiwa gerakan stilus.](https://developer.android.google.cn/static/images/develop/ui/compose/touch-input/stylus-input/shared/edittext_handwriting_bounds.png?authuser=19&hl=id)
EditText
.
Inisiasi tulisan tangan kustom
Jika tampilan berisi beberapa editor teks atau konten selain satu editor teks, tampilan tersebut harus mengimplementasikan logika inisiasi tulisan tangannya sendiri sebagai berikut:
Pilih untuk tidak menggunakan inisiasi tulis tangan otomatis sistem tampilan dengan memanggil
setAutoHandwritingEnabled(false)
.Memantau semua editor teks yang terlihat dalam tampilan.
Memantau peristiwa gerakan yang diterima oleh tampilan di
dispatchTouchEvent()
.Saat gerakan stilus terjadi dalam batas tulisan tangan editor teks, fokuskan editor teks (jika belum difokuskan).
Jika editor belum difokuskan, mulai ulang IME editor dengan konten baru dengan memanggil
InputMethodManager#restartInput()
.Mulai sesi tulis tangan stilus dengan memanggil
InputMethodManager#startStylusHandwriting()
.
Jika editor teks berada dalam tampilan yang dapat di-scroll, gerakan stilus dalam
batas tulisan tangan editor harus dianggap sebagai tulisan tangan, bukan scroll. Gunakan
ViewParent#requestDisallowInterceptTouchEvent()
untuk mencegah tampilan ancestor yang dapat di-scroll mengintersep peristiwa sentuh dari editor
teks.
Detail API
MotionEvent#getToolType()
— Menunjukkan apakahMotionEvent
berasal dari stilus, dalam hal ini nilai yang ditampilkan adalahTOOL_TYPE_STYLUS
atauTOOL_TYPE_ERASER
.InputMethodManager#isStylusHandwritingAvailable()
— Menunjukkan apakah IME mendukung tulisan tangan stilus. Panggil metode ini sebelum setiap panggilan keInputMethodManager#startStylusHandwriting()
karena ketersediaan tulisan tangan mungkin telah berubah.InputMethodManager#startStylusHandwriting()
— Membuat IME masuk ke mode tulis tangan. Peristiwa gerakanACTION_CANCEL
dikirim ke aplikasi untuk membatalkan gestur saat ini. Peristiwa gerakan stilus tidak lagi dikirim ke aplikasi.Peristiwa gerakan stilus dari gestur saat ini yang sudah dikirim ke aplikasi akan diteruskan ke IME. IME diperlukan untuk menampilkan jendela tinta stilus tempat IME menerima semua objek
MotionEvent
berikut. IME meng-commit teks tulisan tangan yang dikenali menggunakanInputConnection
API.Jika IME tidak dapat masuk ke mode tulis tangan, panggilan metode ini tidak beroperasi.
Mendeklarasikan dukungan tulis tangan
Saat mengisi
argumen EditorInfo
dari
View#onCreateInputConnection(EditorInfo)
, panggil
setStylusHandwritingEnabled()
untuk memberi tahu IME bahwa editor teks mendukung tulis tangan.
Deklarasikan gestur yang didukung dengan
setSupportedHandwritingGestures()
dan
setSupportedHandwritingGesturePreviews()
.
Mendukung gestur tulis tangan
IME dapat mendukung berbagai gestur tulis tangan, seperti melingkari teks untuk memilihnya atau mencoret teks untuk menghapusnya.
Editor kustom mengimplementasikan
InputConnection#performHandwritingGesture()
dan
InputConnection#previewHandwritingGesture()
untuk mendukung berbagai jenis
HandwritingGesture
, seperti
SelectGesture
,
DeleteGesture
, dan
InsertGesture
.
Mendeklarasikan gestur tulis tangan yang didukung saat mengisi argumen EditorInfo
dari View#onCreateInputConnection(EditorInfo)
(lihat bagian Mendeklarasikan dukungan
tulisan tangan).
Detail API
InputConnection#performHandwritingGesture(HandwritingGesture, Executor, IntConsumer)
— Mengimplementasikan gestur. ArgumenHandwritingGesture
berisi informasi lokasi yang dapat Anda gunakan untuk menentukan letak gestur dalam teks. Misalnya,SelectGesture
menyediakan objekRectF
yang menentukan rentang teks yang dipilih, danInsertGesture
menyediakan objekPointF
yang menentukan offset teks untuk menyisipkan teks.Gunakan parameter
Executor
danIntConsumer
untuk mengirimkan kembali hasil operasi. Saat argumen eksekutor dan konsumen diberikan, gunakan eksekutor untuk memanggilIntConsumer#accept()
, misalnya:executor.execute { consumer.accept(HANDWRITING_GESTURE_RESULT_SUCCESS) }
HandwritingGesture#getFallbackText()
— Memberikan teks penggantian yang di-commit IME di posisi kursor jika tidak ada teks yang berlaku yang berada di bawah area gestur tulis tangan.Terkadang, IME tidak dapat menentukan apakah gestur stilus dimaksudkan untuk melakukan operasi gestur atau menulis tangan teks. Editor teks kustom bertanggung jawab untuk menentukan maksud pengguna dan melakukan tindakan yang tepat (bergantung pada konteks) di lokasi gestur.
Misalnya, jika IME tidak dapat memastikan apakah pengguna bermaksud menggambar tanda sisipan ke bawah ⋁ untuk melakukan gestur menyisipkan spasi atau menulis tangan huruf "v", IME dapat mengirim
InsertGesture
dengan teks penggantian "v".Editor harus mencoba melakukan gestur sisipkan spasi terlebih dahulu. Jika gestur tidak dapat dilakukan (misalnya, tidak ada teks di lokasi yang ditentukan), editor harus kembali memasukkan "v" pada posisi kursor.
InputConnection#previewHandwritingGesture(PreviewableHandwritingGesture, CancellationSignal)
— Melihat pratinjau gestur yang sedang berlangsung. Misalnya, saat pengguna mulai menggambar lingkaran di sekitar teks, pratinjau langsung dari pilihan yang dihasilkan dapat ditampilkan dan terus diperbarui saat pengguna terus menggambar. Hanya jenis gestur tertentu yang dapat dipratinjau (lihatPreviewableHandwritingGesture
).Parameter
CancellationSignal
dapat digunakan oleh IME untuk membatalkan pratinjau. Jika peristiwa lain mengganggu pratinjau (misalnya, teks diubah secara terprogram atau terjadi perintahInputConnection
baru), editor kustom dapat membatalkan pratinjau.Gestur pratinjau hanya untuk tampilan dan tidak boleh mengubah status editor. Misalnya, pratinjau
SelectGesture
menyembunyikan rentang pilihan editor saat ini dan menandai rentang pratinjau gestur. Namun, setelah pratinjau dibatalkan, editor akan memulihkan rentang pilihan sebelumnya.
Berikan lokasi kursor dan data posisi lainnya
Dalam mode tulis tangan, IME dapat meminta lokasi kursor dan data posisi lainnya
menggunakan
InputConnection#requestCursorUpdates()
.
Editor kustom akan merespons dengan panggilan ke
InputMethodManager#updateCursorAnchorInfo(View,
CursorAnchorInfo)
.
Data dalam
CursorAnchorInfo
yang relevan dengan tulisan tangan stilus disediakan melalui metode
CursorAnchorInfo.Builder
berikut:
setInsertionMarkerLocation()
— Menetapkan lokasi kursor. IME menggunakan nilai tersebut untuk menganimasikan tinta tulisan tangan ke lokasi kursor.setEditorBoundsInfo()
— Menetapkan batas editor dan batas tulisan tangan. IME menggunakan data ini untuk memosisikan toolbar tulisan tangan IME di layar.addVisibleLineBounds()
— Menetapkan batas semua baris teks yang terlihat (atau terlihat sebagian) dari editor. IME menggunakan batas garis untuk meningkatkan akurasi dalam mengenali gestur tulisan tangan.setTextAppearanceInfo()
— Menetapkan tampilan teks dengan informasi yang berasal dari kolom input teks. IME menggunakan informasi tersebut untuk memberi gaya pada tinta tulis tangan.
Tampilkan ikon kursor tulisan tangan stilus
Tampilkan ikon tulisan tangan stilus saat stilus diarahkan ke
batas tulisan tangan editor teks kustom dan IME yang dipilih mendukung
tulisan stilus
(InputMethodManager#isStylusHandwritingAvailable()
).
Ganti
View#onResolvePointerIcon()
agar mendapatkan ikon pengarahan kursor untuk tulisan tangan stilus. Di penggantian, panggil
PointerIcon.getSystemIcon(context, PointerIcon.TYPE_HANDWRITING)
untuk mengakses ikon pengarahan kursor tulis tangan stilus sistem.