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

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

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

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

alt_text

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

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

ويوضّح الجزء المتبقي من هذا المستند هذه الميزات بالتفصيل. للاطّلاع على مثال على استخدام GameTextInput مع GameActivity، يمكنك مراجعة مستودع games-samples.

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

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

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

alt_text

التحقّق من توفّر النص

يتم تمرير أحداث لوحة المفاتيح الافتراضية من 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_pollOnce(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 API

تحصل التطبيقات على النص المُدخَل حاليًا باستخدام آلية رد الاتصال المعتادة:

  • نفِّذ دالة رد اتصال من النوع 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 IssueTracker.