TextInput در GameActivity بخشی از Android Game Development Kit.
GameActivity GameTextInput را با این روشها ادغام میکند:
- ارائه بستهبندیکننده
- ایجاد پرچم برای دردسترس بودن رویداد ورودی نوشتار جدید
- مستقیماً از میانگیر وضعیت GameTextInput برای محتوای نوشتاری استفاده میکند
همانطور که در نمودار زیر نشان داده شده است، برنامهها از مؤلفههای منطقی داخلی متفاوتی برای ورودی نوشتار کاربر استفاده میکنند:

سه مرحله کلی برای استفاده از کتابخانه داخلی GameTextInput وجود دارد:
- کنترل کردن صفحهکلید نرمافزاری در میانای کاربر
- دانستن اینکه چه زمانی نوشتار جدید دردسترس است
- بازیابی نوشتار ورودی کاربر و وضعیتهای آن
بقیه این سند آنها را بهطور مفصل شرح میدهد. برای دیدن نمونهای از
GameTextInput با GameActivity در عمل، به
مخزن games-samples مراجعه کنید.
کنترل کردن صفحهکلید نرمافزاری در میانای کاربر
GameActivity دو عملکرد برای کنترل صفحهکلید نرمافزاری در میانای کاربر ارائه میدهد:
GameActivity_showSoftInput()صفحهکلید نرمافزاری را نمایش میدهد.GameActivity_hideSoftInput()صفحهکلید نرمافزاری را پنهان میکند.
برای تعاریف آنها به اسناد مرجع میانای برنامهسازی کاربردی مراجعه کنید. پساز نمایش صفحهکلید، میانای کاربر برنامه ممکن است شبیه به تصویر زیر باشد:

بررسی دردسترس بودن نوشتار
رویدادهای صفحهکلید نرمافزاری از GameTextInput در سمت Java به سمت C/C++ ازطریق JNI منتقل میشوند، سپس به پوشاننده 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_، جمعآوری میشوند. برنامهها
میتوانند از یکی از روشهای زیر برای بازیابی محتوای خود استفاده کنند:
- میانای برنامهسازی کاربردی دادهپوش GameActivity (توصیهشده)
- GameTextInput API
دریافت وضعیت TextInput با GameActivity API
برنامهها ورودی نوشتاری فعلی را با سازوکار معمول فراخوانی برگشتی دریافت میکنند:
- تابع بازخوانی از نوع
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.
);
}
برنامهها میتوانند بهطور اختیاری محتوای 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
- نمونه agdkTunnel
- سند مرجع Jetpack برای GameActivity
- سند مرجع Jetpack برای GameTextInput
- کد منبع AGDK
بازخورد
GameActivity و GameTextInput هر دو بخشی از کتابخانه بازیهای Jetpack هستند. برای هرگونه مشکل و سؤال، اشکالی در Google IssueTracker ایجاد کنید.