إدخال النص في GameActivity   جزء من Android Game Development Kit

تدمج GameActivity واجهة برمجة التطبيقات GameTextInput من خلال:

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

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

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

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

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

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

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

• تعرض GameActivity_showSoftInput() لوحة المفاتيح الافتراضية.
• يؤدي النقر على GameActivity_hideSoftInput() إلى إخفاء لوحة المفاتيح الافتراضية.

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

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

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

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

الحصول على حالة 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
• نموذج agdkTunnel
• مستندات Jetpack المرجعية الخاصة بـ GameActivity
• المستندات المرجعية الخاصة بـ GameTextInput في Jetpack
• رمز المصدر لمجموعة أدوات تطوير الألعاب على Android

الملاحظات

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