GameTextInput   חלק מ-Android Game Development Kit.

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

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

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

זמינות

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

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

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

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

גרסאות רשמיות של GameTextInput זמינות בגרסה של ספריית המשחקים של Jetpack ב-Google Maven.

הגדרת היצירה

‫GameTextInput מופץ כ-Android Archive‏ (AAR). קובץ ה-AAR הזה מכיל את מחלקות ה-Java ואת קוד המקור ב-C, שמטמיע את התכונות המקוריות של GameTextInput. אתם צריכים לכלול את קובצי המקור האלה כחלק מתהליך ה-build באמצעות 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. בקובצי המקור שמשתמשים ב-API של GameTextInput ב-C, כוללים את קובץ הכותרת:

    #include <game-text-input/gametextinput.h>
    
  6. מריצים את האפליקציה ויוצרים לה קובץ build. אם יש שגיאות CMake, מוודאים שהקבצים של AAR ו-build.gradle מוגדרים כמו שצריך. אם הקובץ #include לא נמצא, צריך לבדוק את קובץ התצורה של CMakeLists.txt.

שילוב ה-build

  1. מה-thread של C שכבר מצורף ל-JVM, או מה-thread הראשי של האפליקציה, קוראים ל-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. זה פשוט יחסית כשמשתמשים ב-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, שמפעיל באופן פנימי את פונקציית ה-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.