GameTextInput   חלק מ-Android Game Development Kit.

השימוש בספרייה GameTextInput הוא חלופה פשוטה יותר לכתיבת אפליקציית Android למסך מלא שמשתמשת במקלדת הוירטואלית להזנת טקסט.

‫GameTextInput מספק API פשוט להצגה או להסתרה של המקלדת הרכה, להגדרה או לקבלת הטקסט שנערך כרגע ולקבלת התראות כשהטקסט משתנה. התכונה הזו לא מיועדת לאפליקציות עריכת טקסט מלאות, אבל היא עדיין מספקת תמיכה באזור בחירה ובאזור כתיבה לתרחישי שימוש טיפוסיים במשחקים. בנוסף, הספרייה הזו תומכת בתכונות מתקדמות של עורך שיטות קלט (IME), כמו בדיקת איות, השלמות ותווים עם כמה מקשים.

באופן פנימי, GameTextInput צובר את טקסט הקלט (יחד עם המצבים הרלוונטיים) במאגר הפנימי GameTextInput::currentState_ ומודיע לאפליקציה על כל שינוי שמתרחש בו. לאחר מכן האפליקציה מבצעת עיבוד טקסט בפונקציית הקריאה החוזרת הרשומה שלה.

זמינות

אפשר להשתמש ב-GameTextInput בדרכים הבאות:

  • יחד עם GameActivity: GameActivity משלב את GameTextInput. באפליקציות שמשתמשות ב-GameActivity אפשר להשתמש רק ב-GameTextInput המשולב. הוראות השימוש מתועדות באופן מלא בדף GameActivity . דוגמה לשילוב של GameActivity ו-GameTextInput זמינה במאגר games-samples. מודל השימוש הזה לא נכלל במדריך הזה.

  • כספרייה עצמאית: שאר המדריך מתאר את שלבי השימוש.

חשוב לזכור שאי אפשר להשתמש בשתי השיטות שצוינו למעלה בו-זמנית.

גרסאות רשמיות של Jetpack זמינות בספריית המשחקים של Jetpack בגרסה [Google Maven][google-maven]{:.external}.GameTextInput

הגדרת ה-build

‫GameTextInput מופץ כארכיון Android‏ (AAR). קובץ ה-AAR הזה מכיל את מחלקות Java ואת קוד המקור של C, שמטמיע את התכונות המקוריות של GameTextInput. צריך לכלול את קובצי המקור האלה כחלק מתהליך הבנייה באמצעות Prefab, שחושף ספריות Native וקוד מקור לפרויקט CMake או ל-NDK build.

  1. פועלים לפי ההוראות בדף Jetpack Android Games כדי להוסיף את התלות בספרייה GameTextInput לקובץ build.gradle של המשחק. הערה: אם האפליקציות שלכם משתמשות ב-GameActivity, אי אפשר להשתמש בספריית GameTextInput העצמאית.

  2. מוודאים שהקובץ gradle.properties מכיל את השורות הבאות:

    # Tell Android Studio we are using AndroidX.
android.useAndroidX=true
# Use Prefab 1.1.2 or higher, which contains a fix for "header only" libs.
android.prefabVersion=1.1.2
# Required only if you're using Android Studio 4.0 (4.1 is recommended).
# android.enablePrefab=true

  3. מייבאים את חבילת game-text-input ומוסיפים אותה ליעד בקובץ CMakeLists.txt של הפרויקט:

    find_package(game-text-input REQUIRED CONFIG)
...
target_link_libraries(... game-text-input::game-text-input)

  4. באחד מקובצי .cpp במשחק, מוסיפים את השורה הבאה כדי לכלול את ההטמעה של GameTextInput:

    #include <game-text-input/gametextinput.cpp>

  5. בקובצי המקור שמשתמשים ב-GameTextInput C API, צריך לכלול את קובץ הכותרת:

    #include <game-text-input/gametextinput.h>

  6. קומפלו את האפליקציה והריצו אותה. אם יש שגיאות ב-CMake, ודאו שהקבצים AAR ו-build.gradle מוגדרים בצורה תקינה. אם הקובץ #include לא נמצא, צריך לאמת את קובץ ההגדרות CMakeLists.txt.

שילוב של הגרסה

  1. משרשור C שכבר מצורף ל-JVM, או מהשרשור הראשי של האפליקציה, קוראים ל-GameTextInput_init עם מצביע JNIEnv.

    static GameTextInput* gameTextInput = nullptr;

extern "C"
JNIEXPORT void JNICALL
Java_com_gametextinput_testbed_MainActivity_onCreated(JNIEnv* env,
  jobject this) {
{
    if(!gameTextInput)
      gameTextInput = GameTextInput_init(env);
    ...
}

  2. יוצרים מחלקת Java עם גישה ל-InputConnection.InputEnabledTextView

    public class InputEnabledTextView extends View implements Listener {
  public InputConnection mInputConnection;
  public InputEnabledTextView(Context context, AttributeSet attrs) {
    super(context, attrs);
  }

  public InputEnabledTextView(Context context) {
    super(context);
  }
  public void createInputConnection(int inputType) {
    EditorInfo editorInfo = new EditorInfo();
    editorInfo.inputType = inputType;
    editorInfo.actionId = IME_ACTION_NONE;
    editorInfo.imeOptions = IME_FLAG_NO_FULLSCREEN;
    mInputConnection = new InputConnection(this.getContext(), this,
            new Settings(editorInfo, true)
    ).setListener(this);
  }

  @Override
  public InputConnection onCreateInputConnection(EditorInfo outAttrs) {
    if (outAttrs != null) {
        GameTextInput.copyEditorInfo(mInputConnection.getEditorInfo(), outAttrs);
    }
    return mInputConnection;
  }

  // Called when the IME input changes.
  @Override
  public void stateChanged(State newState, boolean dismissed) {
    onTextInputEventNative(newState);
  }
  @Override
  public void onImeInsetsChanged(Insets insets) {
    // handle Inset changes here
  }

  private native void onTextInputEventNative(State softKeyboardEvent);
}

  3. מוסיפים את InputEnabledTextView שנוצר לפריסת ממשק המשתמש. לדוגמה, הקוד הבא ב-activity_main.xml יכול למקם את המודעה בתחתית המסך:

    <com.android.example.gametextinputjava.InputEnabledTextView
    android:id="@+id/input_enabled_text_view"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent" />

  4. מאחזרים את המחלקה החדשה InputEnabledTextView לפעילות Java. הפעולה הזו פשוטה יחסית כשמשתמשים ב-View Binding:

    public class MainActivity extends AppCompatActivity {
  ...
  private ActivityMainBinding binding;
  private InputEnabledTextView inputEnabledTextView;

  private native void setInputConnectionNative(InputConnection c);

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    ...
    binding = ActivityMainBinding.inflate(getLayoutInflater());
    inputEnabledTextView = binding.inputEnabledTextView;
    inputEnabledTextView.createInputConnection(InputType.TYPE_CLASS_TEXT);
    setInputConnectionNative(inputEnabledTextView.mInputConnection);
  }

  5. בספריית C, מעבירים את inputConnection אל GameTextInput_setInputConnection. מעבירים קריאה חוזרת (callback) ב-GameTextInput_setEventCallback כדי לקבל התראה על אירועים כמבנה מצב C‏ GameTextInputState.

    extern "C"JNIEXPORT void JNICALL
Java_com_gametextinput_testbed_MainActivity_setInputConnectionNative(
  JNIEnv *env, jobject this, jobject inputConnection) {
  GameTextInput_setInputConnection(gameTextInput, inputConnection);
  GameTextInput_setEventCallback(gameTextInput,[](void *ctx, const GameTexgtInputState *state) {
    if (!env || !state) return;
    // process the newly arrived text input from user.
    __android_log_print(ANDROID_LOG_INFO, "TheGreateGameTextInput", state->text_UTF8);
  }, env);
}

  6. בספריית C, קוראים ל-‎ GameTextInput_processEvent ‎, שקוראת באופן פנימי לקריאה החוזרת שרשומה בשלב הקודם, כדי שהאפליקציה תטפל באירועים כשמצב ההפעלה משתנה.

    extern "C"
JNIEXPORT void JNICALL
Java_com_gametextinput_testbed_InputEnabledTextView_onTextInputEventNative(
  JNIEnv* env, jobject this, jobject soft_keyboard_event) {
  GameTextInput_processEvent(gameTextInput, soft_keyboard_event);
}

פונקציות בסיסיות

הספרייה GameTextInput כוללת פונקציות עזר שמאפשרות לכם להמיר בין אובייקטים של מצב Java לבין מבני מצב C. אפשר לגשת לפונקציות להצגה ולהסתרה של IME דרך הפונקציות GameTextInput_showIme ו-GameTextInput_hideIme.

קובצי עזר

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

משוב

אם יש לך בעיות או שאלות לגבי GameTextInput, אפשר ליצור באג ב-Google IssueTracker.