GameTextInput   חלק מ-Android Game Development Kit.

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

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

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

זמינות

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

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

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

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

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

הגדרת ה-build

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

  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. בקובצי המקור שמשתמשים ב-API ל-C של GameTextInput, צריך לכלול את קובץ הכותרת:

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

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

שילוב ה-build

  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‏ InputEnabledTextView עם גישה אל InputConnection.

    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. כשמשתמשים בקישור תצוגה, זה יחסית פשוט:

    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, שמפעילה באופן פנימי את פונקציית ה-callback שרשומה בשלב הקודם, כדי שהאפליקציה לטפל באירועים כשהמצב משתנה.

    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.