GameActivity 的 TextInput Android Game Development Kit 提供的一項工具
GameActivity 透過以下方式整合 GameTextInput:
- 提供包裝函式
- 為新的文字輸入事件可用性建立旗標
- 直接使用 GameTextInput 進行文字內容的緩衝處理
如以下圖表所示,應用程式會使用不同的內部邏輯元件,以便處理使用者的文字輸入內容:
以下是內建 GameTextInput
程式庫的三個主要步驟:
- 在 UI 上控制螢幕鍵盤
- 瞭解何時有新文字
- 擷取使用者輸入內容文字及其狀態
本文件其他地方會再詳細說明以上內容。如需 GameTextInput
與 GameActivity
實際運作的範例,請參閱「games-samples 存放區」。
在 UI 上控制螢幕鍵盤
GameActivity
提供兩種在 UI 上控制螢幕鍵盤的功能:
GameActivity_showSoftInput()
會顯示螢幕鍵盤。GameActivity_hideSoftInput()
會隱藏螢幕鍵盤。
如要瞭解定義的定義,請參閱「API 參考說明文件」。顯示鍵盤後,應用程式的 UI 看起來可能類似以下內容:
檢查文字可用性
螢幕鍵盤事件透過 JNI 從 Java 端的 GameTextInput
傳遞至 C/C++ 端,接著前往 GameActivity 的包裝函式,最後反映在 native_app_glue
中實作的 android_app::textInputState
旗標上。應用程式應定期輪詢此旗標來執行預期處理:
- 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_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.
}
}
擷取使用者輸入內容文字
遊戲中的輸入內容文字和其他狀態會累積在 GameTextInput 的內部緩衝區 GameTextInput::currentState_
中。應用程式可以使用下列其中一種方式擷取其內容:
- GameActivity 的包裝函式 API (建議)
- GameTextInput API
透過 GameActivity API 取得 TextInput 狀態
應用程式會使用一般回呼機制,取得目前的文字輸入內容:
- 實作
GameTextInputGetStateCallback
類型的回呼函式來處理文字輸入事件。 - 如果有一個或多個未處理的事件,請呼叫
GameActivity_getInputState()
。 - 在事件處理完成後清除
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.
);
}
應用程式可選擇使用 GameActivity_setTextInputState()
初始化 GameTextInputState
內容。
透過 GameTextInput API 取得 TextInput 狀態
應用程式也可以直接使用 GameTextInput
API 擷取目前的 GameTextInputState
:
- 使用
GameActivity_getTextInput()
取得 GameActivity 的內部GameTextInput
執行個體。 - 備妥
GameTextInput
執行個體後,呼叫GameTextInput_getState()
即可取得相同的GameTextInputState
內容。
同樣,應用程式不得直接初始化 GameTextInput
;GameActivity
已在初始化程序中執行這項動作。
回呼機制與 GameActivity 的 GameActivity_getTextInputState()
函式所使用的機制相同。
參考資料
建立 GameActivity
應用程式時,開發人員可能會覺得下列資源有幫助:
- 立即開始使用 GameActivity
- GameTextInput 使用者說明文件
- agdkTunnel 範例
- Jetpack GameActivity 說明文件
- GameActivity 的 Jetpack 參考文件
- AGDK 原始碼
意見回饋
GameActivity 和 GameTextInput 都是 Jetpack 遊戲庫的一部分。如有任何問題和疑問,請在 IssueTracker 上建立錯誤。