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