TextInput ใน GameActivity   ส่วนหนึ่งของชุดพัฒนาเกม Android

GameActivity ผสานรวม GameTextInput โดยทำดังนี้

  • การจัดเตรียม Wrapper
  • สร้างแฟล็กสำหรับความพร้อมใช้งานของเหตุการณ์การป้อนข้อความใหม่
  • โดยตรงโดยใช้บัฟเฟอร์สถานะของ GameTextInput สำหรับเนื้อหาข้อความ

ดังที่แสดงในแผนภาพต่อไปนี้ แอปพลิเคชันใช้คอมโพเนนต์เชิงตรรกะภายในที่แตกต่างกันเพื่อวัตถุประสงค์ในการป้อนข้อความของผู้ใช้

alt_text

การใช้ไลบรารี GameTextInput ในตัวมี 3 ขั้นตอนคร่าวๆ ดังนี้

  • การควบคุมแป้นพิมพ์เสมือนใน UI
  • การทราบเมื่อมีข้อความใหม่
  • การดึงข้อความที่ผู้ใช้ป้อนและสถานะของข้อความ

ส่วนที่เหลือของเอกสารนี้จะอธิบายรายละเอียดของแต่ละวิธี ดูตัวอย่างการใช้งาน GameTextInput กับ GameActivity ได้ที่ที่เก็บ games-samples

ควบคุมแป้นพิมพ์เสมือนใน UI

GameActivity มีฟังก์ชัน 2 อย่างในการควบคุมแป้นพิมพ์เสมือนบน UI ดังนี้

โปรดดูคำจำกัดความในเอกสารอ้างอิง API หลังจากแป้นพิมพ์แสดงขึ้น UI ของแอปพลิเคชันอาจมีลักษณะคล้ายกับภาพต่อไปนี้

alt_text

ตรวจสอบความพร้อมใช้งานของข้อความ

ระบบจะส่งเหตุการณ์แป้นพิมพ์เสมือนจาก GameTextInput ในฝั่ง Java ไปยังฝั่ง C/C++ ผ่าน JNI จากนั้นจะส่งไปยัง Wrapper ของ GameActivity และสุดท้ายจะแสดงในแฟล็ก android_app::textInputState ที่ติดตั้งใช้งานใน native_app_glue แอปพลิเคชันควรตรวจสอบแฟล็กนี้เป็นระยะๆ เพื่อดำเนินการประมวลผลตามที่ต้องการ

  • GameActivity จะตั้งค่าเฉพาะแฟล็ก android_app::textInputState เท่านั้น
  • แอปพลิเคชันจะตรวจสอบแฟล็กและจัดการเหตุการณ์ GameTextInput ใหม่ เช่น ข้อความใหม่ที่เพิ่มลงในบัฟเฟอร์อินพุต
  • แอปพลิเคชันจะล้าง android_app::textInputState

โปรดทราบว่า android_app::textInputState ไม่ได้แยกความแตกต่างระหว่างเหตุการณ์การป้อนข้อความรายการเดียวและหลายรายการ

ตัวอย่างเช่น โค้ดต่อไปนี้จะโพลแฟล็ก textInputState หลังจากจัดการคำสั่งวงจรของแอป การโต้ตอบแบบสัมผัส และเหตุการณ์สำคัญ

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

   while ((ALooper_pollOnce(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.
   }
}

ดึงข้อความที่ผู้ใช้ป้อน

ข้อความที่ป้อนและสถานะอื่นๆ จะสะสมอยู่ในบัฟเฟอร์ภายในของ GameTextInput ซึ่งก็คือ GameTextInput::currentState_ แอปพลิเคชันสามารถใช้วิธีใดวิธีหนึ่งต่อไปนี้เพื่อดึงเนื้อหา

  • Wrapper API ของ GameActivity (แนะนำ)
  • GameTextInput API

รับสถานะ TextInput ด้วย GameActivity API

แอปพลิเคชันจะรับการป้อนข้อความปัจจุบันด้วยกลไก Callback ทั่วไป ดังนี้

  • ใช้ฟังก์ชัน Callback ประเภท GameTextInputGetStateCallback เพื่อประมวลผลเหตุการณ์การป้อนข้อความ
  • เรียกใช้ GameActivity_getInputState() เมื่อมีเหตุการณ์ที่ค้างอยู่ 1 รายการหรือหลายรายการ
  • ล้าง android_app::textInputState หลังจากประมวลผลเหตุการณ์แล้ว

ต่อจากข้อมูลโค้ดในส่วนก่อนหน้า โค้ดต่อไปนี้จะรับการอ้างอิงไปยังบัฟเฟอร์อินพุตข้อความ ประมวลผล (ไม่แสดง) และรีเซ็ตแฟล็กเหตุการณ์

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

ใน Game Loop ที่แสดงในส่วนก่อนหน้า ให้ตรวจสอบและประมวลผลข้อความด้วยเครื่องจัดการการป้อนข้อความก่อนหน้า ดังนี้

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

แอปพลิเคชันสามารถเลือกที่จะเริ่มต้นเนื้อหา GameTextInputState ด้วย GameActivity_setTextInputState() ได้

รับสถานะ TextInput ด้วย GameTextInput API

นอกจากนี้ แอปพลิเคชันยังใช้ GameTextInput API โดยตรงเพื่อดึงข้อมูล GameTextInputState ปัจจุบันได้ด้วย

  • ใช้ GameActivity_getTextInput() เพื่อรับอินสแตนซ์ GameTextInput ภายในของ GameActivity
  • เมื่อมีอินสแตนซ์ GameTextInput แล้ว ให้เรียกใช้ GameTextInput_getState() เพื่อรับเนื้อหา GameTextInputState เดียวกัน

โปรดทราบอีกครั้งว่าแอปพลิเคชันไม่ควรเริ่มต้น GameTextInput โดยตรง เนื่องจาก GameActivity ได้ดำเนินการดังกล่าวแล้วในระหว่างกระบวนการเริ่มต้น

กลไก Callback จะเหมือนกับกลไกที่ใช้โดยฟังก์ชัน GameActivity_getTextInputState() ของ GameActivity

ข้อมูลอ้างอิง

นักพัฒนาแอปอาจพบว่าแหล่งข้อมูลต่อไปนี้มีประโยชน์เมื่อสร้างแอปพลิเคชัน GameActivity

ความคิดเห็น

ทั้ง GameActivity และ GameTextInput เป็นส่วนหนึ่งของคลังเกม Jetpack หากมีปัญหาและข้อสงสัย โปรดสร้างข้อบกพร่องใน Google IssueTracker