TextInput في GameActivity جزء من حزمة تطوير ألعاب Android.

تدمج GameActivity GameTextInput على حسب:

  • توفير برنامج تضمين
  • إنشاء علامة لتوفّر حدث إدخال النص الجديد
  • مباشرةً باستخدام المورد الاحتياطي للحالة الخاص بـ GameTextInput لمحتوى النص

كما هو موضح في الرسم التخطيطي التالي، تستخدم التطبيقات مكونات منطقية داخلية مختلفة لغرض إدخال نص المستخدم:

النص البديل

هناك ثلاث خطوات واسعة لاستخدام مكتبة GameTextInput المدمجة:

  • التحكم في لوحة المفاتيح اللينة على واجهة المستخدم
  • معرفة وقت توفُّر نص جديد
  • استرداد نص إدخال المستخدم وحالاته

وتصف بقية هذا المستند هذه المصطلحات بالتفصيل. للاطّلاع على مثال عن GameTextInput مع تطبيق GameActivity، يمكنك مراجعة مستودع نماذج الألعاب.

التحكم في لوحة المفاتيح اللينة على واجهة المستخدم

يوفر GameActivity وظيفتين للتحكم في لوحة المفاتيح اللينة في واجهة المستخدم:

يُرجى الرجوع إلى المستندات المرجعية لواجهة برمجة التطبيقات للاطّلاع على تعريفاتها. بعد عرض لوحة المفاتيح، قد تظهر واجهة المستخدم للتطبيق بشكل مشابه لما يلي:

النص البديل

التحقّق من توفّر الرسائل النصية

يتم نقل أحداث لوحة المفاتيح اللينة من GameTextInput على جانب Java إلى جانب C/C++ من خلال JNI، ثم ينتقل إلى برنامج تضمين GameActivity، وينعكس ذلك أخيرًا في علامة android_app::textInputState التي تم تنفيذها في native_app_glue. وينبغي للتطبيقات استطلاع هذه العلامة بشكل دوري لإجراء المعالجة المطلوبة:

  • يضبط GameActivity علامة android_app::textInputState فقط.
  • وستبحث التطبيقات عن العلامة وتعالج أحداث GameTextInput الجديدة، مثل النص الجديد الذي تمت إضافته إلى المخزن المؤقت للإدخال.
  • تعمل التطبيقات على محو android_app::textInputState.

تجدر الإشارة إلى أنّ android_app::textInputState لا يفرق بين أحداث إدخال النص الفردي وأحداث إدخال النص المتعدّدة.

على سبيل المثال، يستخلص الرمز التالي علامة textInputState بعد التعامل مع أوامر دورة التطبيق وأحداث اللمس والأحداث الرئيسية:

while (true) {
   // Read all pending events.
   int events;
   struct android_poll_source* source;

   while ((ALooper_pollAll(engine.animating ? 0 : -1, nullptr, &events,
                                 (void**)&source)) >= 0) {
       // Process this event, etc.
       ...
       // Check if we are exiting.
       if (app->destroyRequested != 0) {
           engine_term_display(&engine);
           return;
       }
   }
   engine_handle_input(app);

   // Process text input events if there is any outstanding.
   if (app->textInputState) {
       // process TextInput events.
          ...
       //reset the textInputState flag
       app->textInputState = 0;
   }
   if (engine.animating) {
         // draw frames.
   }
}

استرداد النص الذي أدخله المستخدم

يتم تجميع نصوص الإدخال والحالات الأخرى في المخزن المؤقت الداخلي لـ GameTextInput، GameTextInput::currentState_. ويمكن للتطبيقات استخدام إحدى الطرق التالية لاسترداد محتواها:

  • واجهة برمجة تطبيقات برنامج تضمين GameActivity (خيار يُنصح به)
  • واجهة برمجة تطبيقات GameTextInput

الحصول على حالة TextInput باستخدام واجهة برمجة التطبيقات GameActivity

تحصل التطبيقات على الإدخال النصي الحالي باستخدام آلية معاودة الاتصال النموذجية:

  • يمكنك تنفيذ دالة رد اتصال من النوع GameTextInputGetStateCallback لمعالجة أحداث إدخال النص.
  • يمكنك الاتصال بـ GameActivity_getInputState() عند توفّر فعالية واحدة أو أكثر من الفعاليات البارزة.
  • يمكنك محو android_app::textInputState بعد معالجة الأحداث.

ومتابعةً للمقتطف في القسم السابق، يحصل الرمز التالي على مرجع إلى المخزن المؤقت لإدخال النص، ويعالجه (غير معروض)، ويعيد ضبط علامة الحدث:

extern "C" void GameTextInputGetStateCB(void *ctx, const struct GameTextInputState *state) {
    auto* engine = (struct engine*)ctx;
    if (!engine || !state) return;

    // Process the text event(s).
    LOGI("UserInputText: %s", state->text_UTF8);

    // Clear the text input flag.
    engine->app->textInputState = 0;
}

في حلقة الألعاب الموضحة في القسم السابق، تحقَّق من النص وعالجه باستخدام معالج إدخال النص أعلاه:

if (state->textInputState) {
    GameActivity_getTextInputState(
        app->activity,
        GameTextInputGetStateCB,  // App's event handler shown above.
        &engine // Context to the GameTextInputGetStateCB function.
    );
}

يمكن للتطبيقات إعداد محتوى GameTextInputState اختياريًا باستخدام GameActivity_setTextInputState().

الحصول على حالة TextInput باستخدام GameTextInput API

ويمكن للتطبيقات أيضًا استخدام واجهة برمجة التطبيقات GameTextInput بشكل مباشر لاسترداد رمز GameTextInputState الحالي:

  • يمكنك استخدام GameActivity_getTextInput() للحصول على مثيل GameTextInput الداخلي من GameActivity.
  • بعد الاستلام من المثيل GameTextInput، يمكنك استدعاء GameTextInput_getState() للحصول على محتوى GameTextInputState نفسه.

تجدُر الإشارة مرة أخرى إلى أنّه يجب عدم إعداد GameTextInput مباشرةً في التطبيقات، لأنّ GameActivity تُجري ذلك أثناء عملية الإعداد.

آلية معاودة الاتصال هي نفسها التي تستخدمها دالة GameActivity_getTextInputState() في GameActivity.

المراجع

قد يجد المطوّرون الموارد التالية مفيدة عند إنشاء تطبيقات GameActivity:

ملاحظات

إنّ GameActivity وGameTextInput كلاهما جزء من مكتبة ألعاب Jetpack. إذا كانت لديك أي مشكلات أو أسئلة، يمكنك إنشاء خطأ في أداة تتبع المشكلات من Google.