GameTextInput   เป็นส่วนหนึ่งของชุดเครื่องมือพัฒนาเกม Android

การใช้ไลบรารี GameTextInput เป็นทางเลือกที่ง่ายกว่าการเขียนแอป Android แบบเต็มหน้าจอที่ใช้แป้นพิมพ์เสมือนสำหรับการป้อนข้อความ

GameTextInput มี API ที่ตรงไปตรงมาเพื่อแสดงหรือซ่อนแป้นพิมพ์เสมือน ตั้งค่าหรือรับข้อความที่แก้ไขอยู่ และรับการแจ้งเตือนเมื่อมีการเปลี่ยนแปลงข้อความ ซึ่งไม่ได้มีไว้สำหรับแอปเครื่องมือแก้ไขข้อความเต็มรูปแบบ แต่ยังคงรองรับการเลือกและการเขียนข้อความสำหรับกรณีการใช้งานทั่วไปในเกม นอกจากนี้ ไลบรารีนี้ยังรองรับฟีเจอร์ตัวแก้ไขวิธีการป้อนข้อมูล (IME) ขั้นสูง เช่น การตรวจตัวสะกด การเติมข้อความอัตโนมัติ และอักขระแบบหลายแป้นพิมพ์

ภายใน GameTextInput จะสะสมข้อความที่ป้อน (พร้อมกับสถานะที่เกี่ยวข้อง) ไปยังบัฟเฟอร์ภายใน GameTextInput::currentState_ และแจ้งให้แอปทราบถึงการเปลี่ยนแปลงใดๆ ในบัฟเฟอร์ จากนั้นแอปจะประมวลผลข้อความในฟังก์ชัน Callback ที่ลงทะเบียนไว้

ความพร้อมใช้งาน

คุณใช้ GameTextInput ได้ในลักษณะต่อไปนี้

  • ร่วมกับ GameActivity: GameActivity ผสานรวม GameTextInput แอปพลิเคชันที่ใช้ GameActivity จะใช้ได้เฉพาะ GameTextInput ที่ผสานรวมเท่านั้น วิธีการใช้งานมีระบุไว้อย่างครบถ้วนในหน้า GameActivity ดูตัวอย่างการผสานรวม GameActivity และ GameTextInput ได้ที่ที่เก็บ games-samples รูปแบบการใช้งานนี้ไม่อยู่ในขอบเขตของคู่มือนี้

  • ในฐานะไลบรารีแบบสแตนด์อโลน: ส่วนที่เหลือของคู่มือจะอธิบายขั้นตอนการใช้งาน

โปรดทราบว่าทั้ง 2 วิธีนี้แยกออกจากกันโดยสิ้นเชิง

รุ่น GameTextInput อย่างเป็นทางการพร้อมให้ใช้งานในรุ่นไลบรารีเกม Jetpack ใน Google Maven

ตั้งค่าบิลด์

GameTextInput มีการเผยแพร่เป็น Android Archive (AAR) AAR นี้มีคลาส Java และซอร์สโค้ด C ซึ่งใช้ฟีเจอร์เนทีฟของ GameTextInput คุณต้องรวมไฟล์ต้นฉบับเหล่านี้เป็นส่วนหนึ่งของกระบวนการบิลด์โดยใช้ Prefab ซึ่งจะแสดงไลบรารีแบบเนทีฟและซอร์สโค้ดต่อโปรเจ็กต์ CMake หรือบิลด์ NDK

  1. ทำตามวิธีการในหน้าเกม Android ของ Jetpack เพื่อเพิ่มทรัพยากร Dependency ของไลบรารี 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 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 ที่สร้างขึ้นลงในเลย์เอาต์ของ UI ตัวอย่างเช่น โค้ดต่อไปนี้ใน 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