إدخال النص في نشاط اللعبة جزء من حزمة تطوير ألعاب 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

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

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

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

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

المراجع

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

ملاحظات

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