TextInput ใน GameActivity ส่วนหนึ่งของชุดพัฒนาเกม Android
GameActivity ผสานรวม GameTextInput โดยทำดังนี้
- การจัดเตรียม Wrapper
- สร้างแฟล็กสำหรับความพร้อมใช้งานของเหตุการณ์การป้อนข้อความใหม่
- โดยตรงโดยใช้บัฟเฟอร์สถานะของ GameTextInput สำหรับเนื้อหาข้อความ
ดังที่แสดงในแผนภาพต่อไปนี้ แอปพลิเคชันใช้คอมโพเนนต์เชิงตรรกะภายในที่แตกต่างกันเพื่อวัตถุประสงค์ในการป้อนข้อความของผู้ใช้

การใช้ไลบรารี GameTextInput ในตัวมี 3 ขั้นตอนคร่าวๆ ดังนี้
- การควบคุมแป้นพิมพ์เสมือนใน UI
- การทราบเมื่อมีข้อความใหม่
- การดึงข้อความที่ผู้ใช้ป้อนและสถานะของข้อความ
ส่วนที่เหลือของเอกสารนี้จะอธิบายรายละเอียดของแต่ละวิธี ดูตัวอย่างการใช้งาน GameTextInput กับ GameActivity ได้ที่ที่เก็บ games-samples
ควบคุมแป้นพิมพ์เสมือนใน UI
GameActivity มีฟังก์ชัน 2 อย่างในการควบคุมแป้นพิมพ์เสมือนบน UI ดังนี้
GameActivity_showSoftInput()แสดงแป้นพิมพ์เสมือนGameActivity_hideSoftInput()ซ่อนแป้นพิมพ์เสมือน
โปรดดูคำจำกัดความในเอกสารอ้างอิง API หลังจากแป้นพิมพ์แสดงขึ้น UI ของแอปพลิเคชันอาจมีลักษณะคล้ายกับภาพต่อไปนี้

ตรวจสอบความพร้อมใช้งานของข้อความ
ระบบจะส่งเหตุการณ์แป้นพิมพ์เสมือนจาก 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
- ตัวอย่าง agdkTunnel
- เอกสารอ้างอิง Jetpack สำหรับ GameActivity
- เอกสารอ้างอิง Jetpack สำหรับ GameTextInput
- ซอร์สโค้ด AGDK
ความคิดเห็น
ทั้ง GameActivity และ GameTextInput เป็นส่วนหนึ่งของคลังเกม Jetpack หากมีปัญหาและข้อสงสัย โปรดสร้างข้อบกพร่องใน Google IssueTracker