Editor teks kustom

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:

  1. Aktifkan inisiasi tulis tangan
  2. Mendeklarasikan dukungan tulis tangan
  3. Mendukung gestur tulis tangan (pilih, hapus, masukkan, dan sebagainya)
  4. Memberikan lokasi kursor dan data posisi lainnya ke IME
  5. 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.
Gambar 1. Tulis tangan dalam batas kolom 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:

  1. Pilih untuk tidak menggunakan inisiasi tulis tangan otomatis sistem tampilan dengan memanggil setAutoHandwritingEnabled(false).

  2. Memantau semua editor teks yang terlihat dalam tampilan.

  3. Memantau peristiwa gerakan yang diterima oleh tampilan di dispatchTouchEvent().

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 apakah MotionEvent berasal dari stilus, dalam hal ini nilai yang ditampilkan adalah TOOL_TYPE_STYLUS atau TOOL_TYPE_ERASER.

  • InputMethodManager#isStylusHandwritingAvailable() — Menunjukkan apakah IME mendukung tulisan tangan stilus. Panggil metode ini sebelum setiap panggilan ke InputMethodManager#startStylusHandwriting() karena ketersediaan tulisan tangan mungkin telah berubah.

  • InputMethodManager#startStylusHandwriting() — Membuat IME masuk ke mode tulis tangan. Peristiwa gerakan ACTION_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 menggunakan InputConnection 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.

Gambar 2. Lingkari untuk memilih teks.
Gambar 3. Coret untuk menghapus teks.

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. Argumen HandwritingGesture berisi informasi lokasi yang dapat Anda gunakan untuk menentukan letak gestur dalam teks. Misalnya, SelectGesture menyediakan objek RectF yang menentukan rentang teks yang dipilih, dan InsertGesture menyediakan objek PointF yang menentukan offset teks untuk menyisipkan teks.

    Gunakan parameter Executor dan IntConsumer untuk mengirimkan kembali hasil operasi. Saat argumen eksekutor dan konsumen diberikan, gunakan eksekutor untuk memanggil IntConsumer#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 (lihat PreviewableHandwritingGesture).

    Parameter CancellationSignal dapat digunakan oleh IME untuk membatalkan pratinjau. Jika peristiwa lain mengganggu pratinjau (misalnya, teks diubah secara terprogram atau terjadi perintah InputConnection 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.

Referensi tambahan