TextInput ב-GameActivity חלק מ-Android Game Development Kit.
GameActivity משלב את GameTextInput באמצעות:
- מספקת מעטפת
- יצירת דגל לזמינות של אירוע קלט טקסט חדש
- באופן ישיר באמצעות מאגר המצבים של GameTextInput לתוכן הטקסט
כפי שמוצג בתרשים הבא, אפליקציות משתמשות ברכיבים לוגיים פנימיים שונים למטרת הזנת טקסט של משתמשים:

יש שלושה שלבים כלליים לשימוש בספרייה המובנית של GameTextInput:
- שליטה במקלדת הווירטואלית בממשק המשתמש
- איך יודעים שיש טקסט חדש
- אחזור הטקסט שהמשתמש הזין והמצבים שלו
בהמשך המסמך מתוארים באופן מפורט הרכיבים האלה. במאגר games-samples אפשר לראות דוגמה לשימוש ב-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_. אפליקציות יכולות להשתמש באחת מהדרכים הבאות כדי לאחזר את התוכן:
- 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
- דוגמה ל-agdkTunnel
- מאמרי עזרה של Jetpack בנושא GameActivity
- מאמרי עזרה של Jetpack בנושא GameTextInput
- קוד המקור של AGDK
משוב
GameActivity ו-GameTextInput הם חלק מספריית המשחקים של Jetpack. אם נתקלתם בבעיות או שיש לכם שאלות, אתם יכולים לדווח על באג ב-Google IssueTracker.