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

يتكامل GameActivity مع GameTextInput من خلال:

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

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

نص_alt

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

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

ويصفها الجزء المتبقي من هذا المستند بالتفصيل. للاطّلاع على مثال عن السمة GameTextInput مع تطبيق GameActivity بشكل عملي، يُرجى مراجعة مستودع Games-عيّنات.

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

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

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

نص_alt

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

يتم نقل أحداث لوحة المفاتيح اللينة من 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::currentState_ في GameTextInput. ويمكن للتطبيقات استخدام إحدى الطرق التالية لاسترداد محتواها:

  • واجهة برمجة تطبيقات برنامج تضمين 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

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

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

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

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

المراجع

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

ملاحظات

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