أدوات تحرير نصوص مخصّصة

إنّ أدوات تحرير النصوص المخصّصة هي طرق عرض لا تشكّل مكوّنات EditText أو أدوات WebView نصية، ولكنّها تتيح إدخال النص من خلال تنفيذ onCreateInputConnection() معاودة الاتصال التي يتم استدعاؤها عند التركيز على عرض ويطلب النظام InputConnection للعرض.

يُفترض أن يعرض استدعاء onCheckIsTextEditor() من محرر نصوص مخصص true.

إتاحة الكتابة بخط اليد بقلم الشاشة في أدوات تحرير النصوص المخصّصة

يتوافق Android 14 (المستوى 34 لواجهة برمجة التطبيقات) والإصدارات الأحدث مع إدخال قلم الشاشة في مكوّنات إدخال النص العادية على Android (راجِع إدخال قلم الشاشة في الحقول النصية). ومع ذلك، تتطلب حقول إدخال النصوص المخصّصة (أو أدوات التحرير) تطويرًا إضافيًا.

لإنشاء محرِّر نصوص مخصّص، اتّبِع الخطوات التالية:

  1. تفعيل ميزة بدء الكتابة بخط اليد
  2. توضيح توفّر ميزة الكتابة بخط اليد
  3. دعم إيماءات الكتابة بخط اليد (التحديد والحذف والإدراج وما إلى ذلك)
  4. توفير موقع المؤشر وبيانات الموضع الأخرى إلى أداة IME
  5. عرض رمز التمرير فوق الكتابة بخط اليد بقلم الشاشة

تفعيل ميزة بدء الكتابة بخط اليد

إذا كان العرض يتكون فقط من محرر نصوص واحد، يمكن لنظام العرض بدء الكتابة اليدوية بقلم الشاشة تلقائيًا. بخلاف ذلك، يجب أن ينفِّذ العرض منطق بدء الكتابة بخط اليد الخاص به.

البدء التلقائي للكتابة بخط اليد

إذا كانت إحدى طرق العرض تتضمّن محرِّر نصوص واحدًا بدون أي محتوى آخر، يمكن لطريقة العرض تفعيل البدء التلقائي للكتابة بخط اليد في نظام العرض من خلال طلب الرمز setAutoHandwritingEnabled(true).

عند تفعيل ميزة الكتابة اليدوية تلقائيًا، تبدأ حركة قلم الشاشة من أي مكان ضمن حدود الكتابة بخط اليد في طريقة العرض تلقائيًا. يتلقّى محرّر طريقة الإدخال (IME) أحداث حركة قلم الشاشة وينفّذ النص الذي تم التعرف عليه.

حقل إدخال يحتوي على مستطيل محيط يشير إلى حدود رصد أحداث حركة قلم الشاشة.
الشكل 1. كتابة بخط اليد ضمن حدود الحقل EditText.

بدء الكتابة بخط اليد المخصّص

إذا كانت طريقة العرض تحتوي على العديد من محرري النصوص أو المحتوى بالإضافة إلى محرر نصوص واحد، يجب أن تنفذ طريقة العرض منطق بدء الكتابة بخط اليد على النحو التالي:

  1. يمكنك إيقاف ميزة البدء التلقائي للكتابة بخط اليد في نظام العرض من خلال طلب الرقم setAutoHandwritingEnabled(false).

  2. تتبع جميع أدوات تحرير النصوص التي تظهر في العرض.

  3. يمكنك مراقبة أحداث الحركة التي تتلقّاها المشاهد في dispatchTouchEvent().

    • عند حدوث حركة بقلم الشاشة ضمن حدود الكتابة بخط اليد في محرر النصوص، عليك التركيز على محرر النصوص (إذا لم يكن مركّزًا بالفعل).

    • إذا لم يكن تركيز المحرِّر مركّزًا، يُرجى إعادة تشغيل أداة IME للمحرِّر باستخدام محتوى جديد من خلال طلب الرمز InputMethodManager#restartInput().

    • يمكنك بدء جلسة الكتابة بخط اليد بقلم الشاشة من خلال الاتصال على الرقم InputMethodManager#startStylusHandwriting().

إذا كان محرِّر النصوص متوفرًا في طريقة عرض قابلة للتمرير، يجب اعتبار حركة قلم الشاشة ضمن حدود الكتابة بخط اليد في المحرر عند الكتابة بخط اليد وليس التمرير. استخدِم ViewParent#requestDisallowInterceptTouchEvent() لمنع عرض أصل قابل للتمرير من اعتراض أحداث اللمس من محرِّر نصوص.

تفاصيل واجهة برمجة التطبيقات

  • MotionEvent#getToolType() — يشير إلى ما إذا كان MotionEvent يأتي من قلم الشاشة، وفي هذه الحالة تكون القيمة المعروضة TOOL_TYPE_STYLUS أو TOOL_TYPE_ERASER.

  • InputMethodManager#isStylusHandwritingAvailable() : للإشارة إلى ما إذا كانت أداة IME تتيح الكتابة بخط اليد بقلم الشاشة. عليك استدعاء هذه الطريقة قبل كل استدعاء إلى InputMethodManager#startStylusHandwriting() لأنه من المحتمل أن يكون مدى توفّر الكتابة بخط اليد قد تغيّر.

  • InputMethodManager#startStylusHandwriting() : يؤدي إلى دخول أداة IME إلى وضع الكتابة بخط اليد. يتم إرسال حدث حركة ACTION_CANCEL إلى التطبيق لإلغاء الإيماءة الحالية. لم يعد يتم إرسال أحداث حركة قلم الشاشة إلى التطبيق.

    تتم إعادة توجيه أحداث حركة قلم الشاشة للإيماءة الحالية التي سبق إرسالها إلى التطبيق إلى أداة IME. يجب استخدام أداة IME لعرض نافذة حبر لقلم الشاشة التي تتلقى من خلالها أداة IME جميع كائنات MotionEvent التالية. تتيح أداة IME إنشاء نص الكتابة بخط اليد الذي تم التعرّف عليه باستخدام واجهات برمجة التطبيقات في InputConnection.

    في حال تعذَّر على أداة IME الدخول إلى وضع الكتابة بخط اليد، سيكون طلب الطريقة هذا بيئة مستقلة.

توضيح توفّر ميزة الكتابة بخط اليد

عند ملء الوسيط EditorInfo في View#onCreateInputConnection(EditorInfo) اتصِل بـ setStylusHandwritingEnabled() لإبلاغ أداة IME بأنّ محرِّر النصوص يتيح الكتابة بخط اليد. تعريف الإيماءات المتوافقة باستخدام setSupportedHandwritingGestures() وsetSupportedHandwritingGesturePreviews().

إتاحة إيماءات الكتابة بخط اليد

يمكن أن تتيح أدوات IME عدة إيماءات للكتابة بخط اليد، مثل وضع دائرة حول النص لتحديده أو الكتابة بالخربشة على النص لحذفه.

الشكل 2. دائرة لتحديد النص
الشكل 3. انقر على "خربشة" لحذف النص.

تنفذ أدوات التحرير المخصصة InputConnection#performHandwritingGesture() و InputConnection#previewHandwritingGesture() لدعم أنواع HandwritingGesture مختلفة، مثل SelectGesture وDeleteGesture وInsertGesture.

توضيح إيماءات الكتابة بخط اليد المتوافقة عند ملء وسيطة EditorInfo في View#onCreateInputConnection(EditorInfo) (راجِع قسم إقرار دعم الكتابة بخط اليد)

تفاصيل واجهة برمجة التطبيقات

  • InputConnection#performHandwritingGesture(HandwritingGesture, Executor, IntConsumer) : تنفيذ الإيماءات. تحتوي الوسيطة HandwritingGesture على معلومات الموقع الجغرافي التي يمكنك استخدامها لتحديد مكان تنفيذ الإيماءة في النص. على سبيل المثال، توفّر السمة SelectGesture عنصر RectF يحدد نطاق النص المحدّد، وتوفّر InsertGesture عنصر PointF يحدد إزاحة النص التي يجب إدراج نص عندها.

    استخدم المعلمتين Executor وIntConsumer لإرسال نتيجة العملية. عند توفير كل من وسيطات التنفيذ والمستهلك، استخدِم أداة تنفيذ الطلب للاتصال بـ IntConsumer#accept()، على سبيل المثال:

    
executor.execute { consumer.accept(HANDWRITING_GESTURE_RESULT_SUCCESS) }

  • HandwritingGesture#getFallbackText() : يتم توفير نص احتياطي ينفّذه أداة IME في موضع المؤشر إذا لم يظهر أي نص مناسب أسفل منطقة إيماءة الكتابة بخط اليد.

    في بعض الأحيان، لا يمكن لأداة IME تحديد ما إذا كانت إيماءة قلم الشاشة مخصّصة لتنفيذ عملية إيماءة أو كتابة نص بخط اليد. يكون محرر النصوص المخصّصة مسؤولاً عن تحديد نية المستخدم واتخاذ الإجراء المناسب (حسب السياق) في موقع الإيماءة.

    على سبيل المثال، إذا لم يتمكّن أداة IME من التأكّد مما إذا كان المستخدم يريد رسم علامة إقحام للأسفل ⋁ لتنفيذ إيماءة إدراج مسافة أو كتابة الحرف "v" يدويًا، يمكن لأداة IME إرسال InsertGesture مع النص الاحتياطي "v".

    يجب أن يحاول المحرِّر أولاً تنفيذ إيماءة إدراج مسافة. إذا تعذّر تنفيذ الإيماءة (على سبيل المثال، لا يوجد نص في الموقع المحدد)، يجب أن يعود المحرر لإدراج "v" عند موضع المؤشر.

  • InputConnection#previewHandwritingGesture(PreviewableHandwritingGesture, CancellationSignal) : يتيح هذا الإعداد معاينة إيماءة جارية. على سبيل المثال، عندما يبدأ المستخدم في رسم دائرة حول نص ما، يمكن عرض معاينة مباشرة للتحديد الناتج وتحديثها باستمرار بينما يواصل المستخدم الرسم. لا يمكن معاينة سوى أنواع معيّنة من الإيماءات (يمكنك الاطّلاع على PreviewableHandwritingGesture).

    يمكن استخدام المعلَمة CancellationSignal بواسطة أداة IME لإلغاء المعاينة. إذا أدّت أحداث أخرى إلى إيقاف المعاينة (على سبيل المثال، تم تغيير النص آليًا أو حدوث أوامر InputConnection جديدة)، يمكن للمحرِّر المخصّص إلغاء المعاينة.

    إيماءات المعاينة للعرض فقط ويجب ألا تؤدي إلى تغيير حالة المحرّر. على سبيل المثال، تخفي معاينة SelectGesture نطاق الاختيار الحالي للمحرر وتُبرز نطاق معاينة الإيماءات. ولكن بعد إلغاء المعاينة، يجب أن يستعيد المحرر نطاق التحديد السابق.

توفير موقع المؤشر وبيانات الموضع الأخرى

في وضع الكتابة بخط اليد، يمكن لأداة IME طلب موقع المؤشر وبيانات الموضع الأخرى باستخدام InputConnection#requestCursorUpdates(). يستجيب المحرِّر المخصّص باستدعاء InputMethodManager#updateCursorAnchorInfo(View, CursorAnchorInfo). يتم توفير البيانات في قسم CursorAnchorInfo ذات الصلة بالكتابة بخط اليد بقلم الشاشة من خلال طرق CursorAnchorInfo.Builder التالية:

  • setInsertionMarkerLocation() — لضبط موقع المؤشر. يستخدم IME القيمة لتحريك حبر الكتابة بخط اليد إلى موقع المؤشر.
  • setEditorBoundsInfo() : تتيح ضبط حدود المحرِّر وحدود الكتابة بخط اليد. ويستخدم أداة IME هذه البيانات لوضع شريط أدوات الكتابة بخط اليد في أداة IME على الشاشة.
  • addVisibleLineBounds() — لضبط حدود جميع أسطر النص المرئية (أو المرئية جزئيًا) للمحرر. يستخدم أداة IME حدود الخط لتحسين الدقة في التعرّف على إيماءات الكتابة بخط اليد.
  • setTextAppearanceInfo() — لضبط مظهر النص بالمعلومات المستمدة من حقل إدخال النص. وتستخدم أداة IME المعلومات لتصميم نمط الحبر المكتوب بخط اليد.

عرض رمز التمرير فوق الكتابة بخط اليد بقلم الشاشة

يمكنك عرض رمز التمرير بالكتابة بخط اليد بقلم الشاشة عندما يمرِّر قلم الشاشة فوق حدود الكتابة بخط اليد في محرِّر النصوص المخصّصة ويتوافق أداة IME المحدّدة مع الكتابة بخط اليد بقلم الشاشة (InputMethodManager#isStylusHandwritingAvailable()).

إلغاء View#onResolvePointerIcon() للحصول على رمز التمرير للكتابة بخط اليد بقلم الشاشة. في خيار الإلغاء، يمكنك استدعاء الرمز PointerIcon.getSystemIcon(context, PointerIcon.TYPE_HANDWRITING) للوصول إلى رمز التمرير الخاص بالكتابة بخط اليد في النظام.

مصادر إضافية