TextInput في GameActivity جزء من مجموعة أدوات تطوير ألعاب Android.
يتكامل GameActivity مع GameTextInput من خلال:
- توفير برنامج تضمين
- إنشاء علامة لمدى توفُّر حدث إدخال نص جديد
- مباشرةً باستخدام المورد الاحتياطي للحالة في GameTextInput للمحتوى النصي
كما هو موضح في المخطط التالي، تستخدم التطبيقات مكونات منطقية داخلية مختلفة لغرض إدخال النص للمستخدم:
هناك ثلاث خطوات واسعة لاستخدام مكتبة GameTextInput
المضمَّنة:
- التحكم في لوحة المفاتيح اللينة على واجهة المستخدم
- معرفة وقت توفُّر نص جديد
- استرداد نص إدخال المستخدم وحالاته
ويصفها الجزء المتبقي من هذا المستند بالتفصيل. للاطّلاع على مثال عن السمة GameTextInput
مع تطبيق GameActivity
بشكل عملي، يُرجى مراجعة مستودع Games-عيّنات.
التحكم في لوحة المفاتيح اللينة على واجهة المستخدم
يوفر 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::currentState_
في GameTextInput. ويمكن للتطبيقات استخدام إحدى الطرق التالية لاسترداد محتواها:
- واجهة برمجة تطبيقات برنامج تضمين 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
ويمكن للتطبيقات أيضًا استخدام واجهة برمجة التطبيقات 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.