TextInput في GameActivity جزء من حزمة تطوير ألعاب Android.
تتكامل 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
الحصول على حالة 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 مباشرةً لاسترداد
GameTextInputState الحالي:
- استخدِم
GameActivity_getTextInput()للحصول على مثيلGameTextInputالداخلي في GameActivity. - باستخدام مثيل
GameTextInput، يمكنك استدعاءGameTextInput_getState()للحصول على محتوىGameTextInputStateنفسه.
يُرجى العِلم مرة أخرى أنّ التطبيقات يجب ألا تبدأ GameTextInput
مباشرةً، لأنّ GameActivity ينفّذ ذلك أثناء عملية الإعداد.
آلية معاودة الاتصال هي نفسها المستخدَمة في دالة GameActivity_getTextInputState() في GameActivity.
المراجع
قد يجد المطوّرون المراجع التالية مفيدة عند إنشاء تطبيقات GameActivity:
- بدء استخدام GameActivity
- مستندات مستخدم GameTextInput
- نموذج agdkTunnel
- مستندات Jetpack المرجعية حول GameActivity
- مستندات Jetpack المرجعية حول GameTextInput
- الرمز المصدر لمجموعة أدوات تطوير الألعاب على Android
الملاحظات
GameActivity وGameTextInput هما جزء من مكتبة ألعاب Jetpack. إذا واجهت أي مشاكل أو كانت لديك أسئلة، يمكنك الإبلاغ عن خطأ في Google IssueTracker.