TextInput ใน GameActivity   ส่วนหนึ่งของ Android Game Development Kit

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 และสุดท้ายจะแสดงใน Flag android_app::textInputState ที่ติดตั้งใช้งานใน native_app_glue แอปพลิเคชัน ควรถามสถานะของแฟล็กนี้เป็นระยะๆ เพื่อทำการประมวลผลตามที่ต้องการ

  • GameActivity จะตั้งค่าเฉพาะแฟล็ก android_app::textInputState
  • แอปพลิเคชันจะสำรวจสถานะของ Flag และจัดการเหตุการณ์ 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_ แอปพลิเคชัน สามารถใช้วิธีใดวิธีหนึ่งต่อไปนี้เพื่อดึงเนื้อหา

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

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

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

  • ใช้ฟังก์ชันเรียกกลับประเภท 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;
}

ในลูปเกมที่แสดงในส่วนก่อนหน้า ให้ตรวจสอบและประมวลผลข้อความ ด้วยตัวแฮนเดิลอินพุตข้อความด้านบน

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 จะดำเนินการดังกล่าวอยู่แล้วในกระบวนการเริ่มต้น

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

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

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

ความคิดเห็น

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