GameTextInput   Một phần của Android Game Development Kit.

Dùng thư viện GameTextInput là giải pháp thay thế đơn giản hơn để viết ứng dụng Android toàn màn hình và sử dụng bàn phím mềm để nhập văn bản.

GameTextInput cung cấp một API đơn giản để hiện hoặc ẩn bàn phím mềm, đặt hoặc nhận văn bản đang chỉnh sửa, đồng thời nhận thông báo khi văn bản đó thay đổi. Thư viện này không dành cho các ứng dụng chỉnh sửa văn bản hoàn chỉnh, nhưng vẫn hỗ trợ việc lựa chọn và soạn thảo văn bản cho các trường hợp sử dụng thông thường trong trò chơi. Ngoài ra, thư viện này còn hỗ trợ các tính năng nâng cao trong trình chỉnh sửa phương thức nhập (IME), chẳng hạn như kiểm tra lỗi chính tả, tự động hoàn thành và ký tự nhiều phím.

Trong nội bộ, GameTextInput sẽ tích luỹ văn bản nhập (cùng với các trạng thái liên quan) vào bộ đệm nội bộ GameTextInput::currentState_ và thông báo cho ứng dụng về mọi thay đổi trong bộ đệm đó. Sau đó, ứng dụng này sẽ xử lý văn bản trong hàm callback đã đăng ký.

Phạm vi cung cấp

Có thể sử dụng GameTextInput theo các cách sau:

  • Cùng với GameActivity: GameActivity tích hợp GameTextInput. Các ứng dụng dùng GameActivity chỉ có thể sử dụng GameTextInput được tích hợp. Bạn có thể xem hướng dẫn sử dụng được ghi lại đầy đủ trên trang GameActivity. Để xem mẫu tích hợp GameActivity và GameTextInput, vui lòng tham khảo kho lưu trữ mẫu trò chơi. Mô hình sử dụng không nằm trong phạm vi của hướng dẫn này.

  • Tương tự một thư viện độc lập: phần còn lại của hướng dẫn có mô tả các bước sử dụng.

Lưu ý là 2 phương pháp trên không thể được dùng đồng thời.

Các bản phát hành chính thức của GameTextInput có sẵn trên những kênh sau:

Hướng dẫn này bao gồm cả trường hợp sử dụng đầu tiên. Để sử dụng các bản phát hành tệp zip, vui lòng tham khảo hướng dẫn được vận chuyển trong gói.

Thiết lập bản dựng

GameTextInput được phân phối dưới dạng một Android Archive (AAR). AAR này chứa các lớp Java và mã nguồn C, các đoạn mã này triển khai những tính năng gốc của GameTextInput. Bạn cần đưa các tệp nguồn này vào quá trình xây dựng thông qua Prefab để hiển thị thư viện gốc và mã nguồn cho Dự án CMake hoặc bản dựng NDK.

  1. Làm theo hướng dẫn trên trang Jetpack Android Games để thêm phần phụ thuộc thư viện GameTextInput vào tệp build.gradle của trò chơi. Lưu ý: Nếu ứng dụng của bạn đang sử dụng GameActivity, thì ứng dụng đó không thể sử dụng thư viện GameTextInput độc lập.

  2. Hãy đảm bảo gradle.properties chứa các dòng sau:

    # 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. Nhập gói game-text-input và thêm gói đó vào mục tiêu của bạn trong tệp CMakeLists.txt của dự án:

    find_package(game-text-input REQUIRED CONFIG)
    ...
    target_link_libraries(... game-text-input::game-text-input)
    
  4. Tại một trong các tệp .cpp trong trò chơi, hãy thêm dòng sau để triển khai GameTextInput:

    #include <game-text-input/gametextinput.cpp>
    
  5. Trong các tệp nguồn sử dụng API ngôn ngữ C GameTextInput, hãy đưa vào tệp tiêu đề:

    #include <game-text-input/gametextinput.h>
    
  6. Biên dịch và chạy ứng dụng. Nếu bạn gặp lỗi CMake, hãy xác minh xem liệu AAR và tệp build.gradle có được thiết lập đúng cách hay không. Nếu không tìm thấy tệp #include, hãy xác minh tệp cấu hình CMakeLists.txt.

Tích hợp bản dựng

  1. Từ chuỗi C đã được đính kèm vào JVM hoặc chuỗi chính của ứng dụng, hãy gọi GameTextInput_init bằng con trỏ 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. Tạo một lớp Java InputEnabledTextView với quyền truy cập vào 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. Thêm InputEnabledTextView đã tạo vào bố cục của giao diện người dùng. Ví dụ: đoạn mã sau đây trong activity_main.xml có thể đặt ở cuối màn hình:

    <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. Truy xuất lớp InputEnabledTextView mới này vào hoạt động Java của bạn. Việc này khá đơn giản khi bạn dùng 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. Trong thư viện C của bạn, hãy truyền inputConnection vàoGameTextInput_setInputConnection. Truyền một lệnh gọi lại vào GameTextInput_setEventCallback để được thông báo về các sự kiện dưới dạng cấu trúc (struct) trạng thái 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. Trong thư viện C, hãy gọi GameTextInput_processEvent để gọi nội bộ cho lệnh callback đã đăng ký ở bước trước, để ứng dụng của bạn có thể xử lý các sự kiện khi trạng thái thay đổi.

    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);
    }
    

Hàm hiệu dụng

Thư viện GameTextInput có các hàm hiệu dụng cho phép bạn chuyển đổi giữa các đối tượng trạng thái Java và cấu trúc trạng thái C, cũng như truy cập các chức năng để hiện và ẩn IME thông qua các hàm GameTextInput_showImeGameTextInput_hideIme.

Tài liệu tham khảo

Các nhà phát triển có thể thấy những thông tin dưới đây hữu ích khi tạo ứng dụng bằng GameTextInput:

Ý kiến phản hồi

Nếu bạn có vấn đề và câu hỏi liên quan đến GameTextInput, vui lòng tạo lỗi trên IssueTracker của Google.