TextInput in GameActivity   Part of Android Game Development Kit.

‫GameActivity משלב את GameTextInput על ידי:

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

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

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

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

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

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

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

• ‫GameActivity_showSoftInput() מציג את המקלדת הווירטואלית.
• ‫GameActivity_hideSoftInput() מסתיר את המקלדת הווירטואלית.

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

בדיקת זמינות הטקסט

אירועים של מקלדת וירטואלית מועברים מ-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’s wrapper API (מומלץ)
• 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().

קבלת מצב של קלט טקסט באמצעות GameTextInput API

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

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

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

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

קובצי עזר

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

• איך מתחילים להשתמש ב-GameActivity
• תיעוד למשתמשים של GameTextInput
• agdkTunnel sample
• מאמרי עזרה בנושא GameActivity ב-Jetpack
• מסמכי עזר של Jetpack בנושא GameTextInput
• קוד המקור של AGDK

משוב

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