TextInput trong GameActivity   Một phần của Android Game Development Kit.

GameActivity tích hợp GameTextInput bằng cách:

• cung cấp một trình bao bọc
• tạo cờ cho tính sẵn có của sự kiện nhập văn bản mới
• trực tiếp sử dụng bộ đệm trạng thái của GameTextInput cho nội dung văn bản

Như minh họa trong sơ đồ sau, các ứng dụng dùng nhiều thành phần logic bên trong cho mục đích nhập văn bản của người dùng:

Có ba bước rộng để sử dụng thư viện GameTextInput tích hợp sẵn:

• Điều khiển bàn phím mềm trên giao diện người dùng
• Biết khi nào có văn bản mới
• Truy xuất văn bản nhập của người dùng và trạng thái của văn bản đó

Phần còn lại của tài liệu sẽ mô tả chi tiết về nội dung này. Để xem ví dụ về GameTextInput với GameActivity đang hoạt động, vui lòng tham khảo kho lưu trữ mẫu trò chơi.

Điều khiển bàn phím mềm trên giao diện người dùng

GameActivity cung cấp hai chức năng để điều khiển bàn phím mềm trên giao diện người dùng:

• GameActivity_showSoftInput() hiển thị bàn phím mềm.
• GameActivity_hideSoftInput() ẩn bàn phím mềm.

Hãy xem tài liệu tham khảo API để biết các định nghĩa. Sau khi bàn phím hiển thị, giao diện người dùng của ứng dụng có thể trông giống như sau:

Kiểm tra khả năng sử dụng văn bản

Sự kiện bàn phím mềm được chuyển từGameTextInput ở phía Java sang bên C/C++ thông qua JNI, sau đó chuyển đến bao bọc của GameActivity, cuối cùng phản chiếu trong cờ android_app::textInputState được triển khai trong native_app_glue. Các ứng dụng phải thăm dò cờ này theo định kỳ để thực hiện quá trình xử lý dự định:

• GameActivity chỉ đặt cờ android_app::textInputState.
• Các ứng dụng sẽ thăm dò cờ và xử lý các sự kiện GameTextInput mới, chẳng hạn như văn bản mới được thêm vào bộ đệm nhập.
• Các ứng dụng sẽ xoá android_app::textInputState.

Xin lưu ý rằng android_app::textInputState không phân biệt giữa sự kiện nhập nhiều văn bản và đơn lẻ.

Ví dụ dễ hiểu: những đoạn mã sau đây thăm dò cờ textInputState sau khi xử lý lệnh của chu kỳ ứng dụng, sự kiện chạm và sự kiện quan trọng:

while (true) {
   // Read all pending events.
   int events;
   struct android_poll_source* source;

   while ((ALooper_pollAll(engine.animating ? 0 : -1, nullptr, &events,
                                 (void**)&source)) >= 0) {
       // Process this event, etc.
       ...
       // Check if we are exiting.
       if (app->destroyRequested != 0) {
           engine_term_display(&engine);
           return;
       }
   }
   engine_handle_input(app);

   // Process text input events if there is any outstanding.
   if (app->textInputState) {
       // process TextInput events.
          ...
       //reset the textInputState flag
       app->textInputState = 0;
   }
   if (engine.animating) {
         // draw frames.
   }
}

Truy xuất văn bản nhập của người dùng

Văn bản đầu vào và các trạng thái khác được tích luỹ trong bộ đệm nội bộ của GameTextInput, GameTextInput::currentState_. Ứng dụng có thể dùng một trong những cách sau để truy xuất nội dung:

• API trình bao bọc của GameActivity (nên dùng)
• API GameTextInput

Nhận trạng thái TextInput bằng API GameActivity

Các ứng dụng nhận được dữ liệu đầu vào văn bản hiện tại với cơ chế gọi lại thông thường:

• Triển khai hàm gọi lại thuộc loại GameTextInputGetStateCallback để xử lý các sự kiện nhập văn bản.
• Gọi GameActivity_getInputState() khi có một hoặc nhiều sự kiện nổi bật.
• Xoá android_app::textInputState sau khi các sự kiện được xử lý.

Tiếp tục với đoạn mã trong phần trước, mã sau đây sẽ thu nạp tệp tham chiếu đến bộ đệm nhập văn bản, xử lý mã đó (không hiển thị) và đặt lại cờ sự kiện:

extern "C" void GameTextInputGetStateCB(void *ctx, const struct GameTextInputState *state) {
    auto* engine = (struct engine*)ctx;
    if (!engine || !state) return;

    // Process the text event(s).
    LOGI("UserInputText: %s", state->text_UTF8);

    // Clear the text input flag.
    engine->app->textInputState = 0;
}

Trong vòng lặp trò chơi hiển thị trong phần trước, hãy kiểm tra và xử lý văn bản bằng trình xử lý nhập văn bản ở trên:

if (state->textInputState) {
    GameActivity_getTextInputState(
        app->activity,
        GameTextInputGetStateCB,  // App's event handler shown above.
        &engine // Context to the GameTextInputGetStateCB function.
    );
}

Các ứng dụng có thể tuỳ ý khởi chạy nội dung GameTextInputState bằng GameActivity_setTextInputState().

Nhận trạng thái TextInput bằng API GameTextInput

Các ứng dụng cũng có thể trực tiếp sử dụng API GameTextInput để truy xuất GameTextInputState hiện tại:

• Dùng GameActivity_getTextInput() để nhận bản sao nội bộ GameTextInput của GameActivity.
• Với bản sao GameTextInput trong tay, hãy gọi GameTextInput_getState() để nhận cùng một nội dung GameTextInputState.

Xin nhắc lại rằng ứng dụng không được khởi chạy GameTextInput trực tiếp; GameActivity đã làm việc đó trong quá trình khởi tạo.

Cơ chế gọi lại giống với cơ chế sử dụng hàm GameActivity_getTextInputState() của GameActivity.

Tệp đối chiếu

Nhà phát triển có thể thấy các tài nguyên hữu ích sau đây khi tạo ứng dụng GameActivity:

• Bắt đầu GameActivity
• Tài liệu dành cho người dùng GameTextInput
• Mẫu agdkTunnel
• Tài liệu tham khảo về Jetpack cho GameActivity
• Tài liệu tham khảo về Jetpack cho GameTextInput
• Mã nguồn AGDK

Phản hồi

Cả GameActivity và GameTextInput đều là một phần của thư viện trò chơi Jetpack. Đối với bất kỳ vấn đề và câu hỏi nào, hãy tạo lỗi trên IssueTracker của Google.