‫TextInput ב-GameActivity   חלק מ-Android Game Development Kit.

‫GameActivity משלב את GameTextInput באמצעות:

  • מספקת מעטפת
  • יצירת דגל לזמינות של אירוע קלט טקסט חדש
  • באופן ישיר באמצעות מאגר המצבים של GameTextInput לתוכן הטקסט

כפי שמוצג בתרשים הבא, אפליקציות משתמשות ברכיבים לוגיים פנימיים שונים למטרת הזנת טקסט של משתמשים:

alt_text

יש שלושה שלבים כלליים לשימוש בספרייה המובנית של GameTextInput:

  • שליטה במקלדת הווירטואלית בממשק המשתמש
  • איך יודעים שיש טקסט חדש
  • אחזור הטקסט שהמשתמש הזין והמצבים שלו

בהמשך המסמך מתוארים באופן מפורט הרכיבים האלה. במאגר games-samples אפשר לראות דוגמה לשימוש ב-GameTextInput עם GameActivity.

שליטה במקלדת הווירטואלית בממשק המשתמש

‫GameActivity מספק שתי פונקציות לשליטה במקלדת הווירטואלית בממשק המשתמש:

ההגדרות שלהם מפורטות במאמרי העזרה של ה-API. אחרי שהמקלדת מוצגת, ממשק המשתמש של האפליקציה עשוי להיראות כך:

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_. אפליקציות יכולות להשתמש באחת מהדרכים הבאות כדי לאחזר את התוכן:

  • ‫API של מעטפת GameActivity (מומלץ)
  • GameTextInput API

קבלת מצב TextInput באמצעות GameActivity API

אפליקציות מקבלות את קלט הטקסט הנוכחי באמצעות מנגנון הקריאה החוזרת (callback) הרגיל:

  • מטמיעים פונקציית קריאה חוזרת מסוג 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;
}

בלולאת המשחק שמוצגת בקטע הקודם, בודקים ומעבדים טקסט באמצעות ה-handler הקודם של קלט הטקסט:

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

אפליקציות יכולות גם להשתמש ישירות ב-API של GameTextInput כדי לאחזר את הערך הנוכחי של GameTextInputState:

  • משתמשים ב-GameActivity_getTextInput() כדי לקבל את המכונה הפנימית של GameTextInput ב-GameActivity.
  • אחרי שמקבלים את המכונה של GameTextInput, מפעילים את GameTextInput_getState() כדי לקבל את אותו תוכן של GameTextInputState.

חשוב לזכור: האפליקציות לא אמורות להפעיל את GameTextInput באופן ישיר. GameActivity כבר עושה את זה בתהליך ההפעלה שלו.

מנגנון הקריאה החוזרת זהה לזה שמשמש את הפונקציה GameActivity_getTextInputState() של GameActivity.

קובצי עזר

מפתחים יכולים להיעזר במקורות המידע הבאים כשהם יוצרים אפליקציות ל-GameActivity:

משוב

‫GameActivity ו-GameTextInput הם חלק מספריית המשחקים של Jetpack. אם נתקלתם בבעיות או שיש לכם שאלות, אתם יכולים לדווח על באג ב-Google IssueTracker.