GameTextInput جزء من مجموعة تطوير ألعاب Android.
يُعدّ استخدام مكتبة GameTextInput بديلاً أبسط
لكتابة تطبيق Android بملء الشاشة يستخدم لوحة المفاتيح الافتراضية لإدخال
النص.
توفّر واجهة برمجة التطبيقات GameTextInput طريقة مباشرة لإظهار لوحة المفاتيح الافتراضية أو إخفائها، وضبط النص الذي يتم تعديله حاليًا أو الحصول عليه، وتلقّي إشعارات عند تغيير النص. هذه الميزة غير مخصّصة لتطبيقات محرِّر النصوص الكاملة، ولكنّها تتيح تحديد النصوص وإنشاءها لحالات الاستخدام المعتادة في الألعاب. تتيح هذه المكتبة أيضًا ميزات محرر أسلوب الإدخال (IME) المتقدّمة، مثل التدقيق الإملائي والإكمال التلقائي والأحرف المتعددة المفاتيح.
داخليًا، يجمع GameTextInput النص المُدخَل (مع الحالات ذات الصلة) في المخزن المؤقت الداخلي GameTextInput::currentState_ ويُعلم التطبيق بأي تغييرات فيه. بعد ذلك، ينفّذ التطبيق معالجة النص في دالّة رد الاتصال
المسجَّلة.
مدى التوفّر
يمكن استخدام "GameTextInput" بالطرق التالية:
مع GameActivity: تدمج GameActivity واجهة GameTextInput. لا يمكن للتطبيقات التي تستخدم GameActivity استخدام سوى GameTextInput المدمج. يتم توثيق تعليمات الاستخدام بالكامل في صفحة GameActivity. للحصول على نموذج لدمج GameActivity وGameTextInput، يُرجى الاطّلاع على مستودع نماذج الألعاب. لا يندرج نموذج الاستخدام هذا ضمن نطاق هذا الدليل.
كمكتبة مستقلة: يوضّح الجزء المتبقي من الدليل خطوات الاستخدام.
يُرجى العِلم أنّ هاتين الطريقتين متنافيتان.
تتوفّر إصدارات GameTextInput الرسمية في إصدار مكتبة ألعاب Jetpack في Google Maven.
إعداد الإصدار
يتم توزيع GameTextInput كـ أرشيف Android (AAR).
يحتوي ملف AAR هذا على فئات Java والرمز المصدر C، الذي ينفّذ الميزات الأصلية لـ GameTextInput. يجب تضمين ملفات المصدر هذه كجزء من عملية الإنشاء باستخدام Prefab، الذي يعرض المكتبات المجمّعة من رموز برمجية أصلية والرمز المصدر في مشروع CMake أو إصدار NDK.
اتّبِع التعليمات الواردة في صفحة ألعاب Jetpack Android لإضافة تبعية مكتبة
GameTextInputإلى ملفbuild.gradleفي لعبتك. يُرجى العِلم أنّه إذا كانت تطبيقاتك تستخدم GameActivity، لا يمكنها استخدام مكتبةGameTextInputالمستقلة.تأكَّد من أنّ
gradle.propertiesيحتوي على الأسطر التالية:# Tell Android Studio we are using AndroidX. android.useAndroidX=true # Use Prefab 1.1.2 or higher, which contains a fix for "header only" libs. android.prefabVersion=1.1.2 # Required only if you're using Android Studio 4.0 (4.1 is recommended). # android.enablePrefab=trueاستورِد حزمة
game-text-inputوأضِفها إلى هدفك في ملفCMakeLists.txtالخاص بمشروعك:find_package(game-text-input REQUIRED CONFIG) ... target_link_libraries(... game-text-input::game-text-input)في أحد ملفات
.cppفي لعبتك، أضِف السطر التالي لتضمين تنفيذGameTextInput:#include <game-text-input/gametextinput.cpp>في الملفات المصدر التي تستخدم واجهة برمجة التطبيقات
GameTextInputC، يجب تضمين ملف العنوان:#include <game-text-input/gametextinput.h>اجمع التطبيق وشغِّله. إذا ظهرت لك أخطاء في CMake، تأكَّد من إعداد ملفات AAR و
build.gradleبشكل صحيح. إذا لم يتم العثور على ملف#include، يُرجى التحقّق من ملف إعدادCMakeLists.txt.
دمج الإصدار
من سلسلة محادثات C المرتبطة حاليًا بـ JVM أو سلسلة المحادثات الرئيسية للتطبيق، يمكنك استدعاء
GameTextInput_initباستخدام مؤشرJNIEnv.static GameTextInput* gameTextInput = nullptr; extern "C" JNIEXPORT void JNICALL Java_com_gametextinput_testbed_MainActivity_onCreated(JNIEnv* env, jobject this) { { if(!gameTextInput) gameTextInput = GameTextInput_init(env); ... }أنشئ فئة Java باسم
InputEnabledTextViewيمكنها الوصول إلىInputConnection.public class InputEnabledTextView extends View implements Listener { public InputConnection mInputConnection; public InputEnabledTextView(Context context, AttributeSet attrs) { super(context, attrs); } public InputEnabledTextView(Context context) { super(context); } public void createInputConnection(int inputType) { EditorInfo editorInfo = new EditorInfo(); editorInfo.inputType = inputType; editorInfo.actionId = IME_ACTION_NONE; editorInfo.imeOptions = IME_FLAG_NO_FULLSCREEN; mInputConnection = new InputConnection(this.getContext(), this, new Settings(editorInfo, true) ).setListener(this); } @Override public InputConnection onCreateInputConnection(EditorInfo outAttrs) { if (outAttrs != null) { GameTextInput.copyEditorInfo(mInputConnection.getEditorInfo(), outAttrs); } return mInputConnection; } // Called when the IME input changes. @Override public void stateChanged(State newState, boolean dismissed) { onTextInputEventNative(newState); } @Override public void onImeInsetsChanged(Insets insets) { // handle Inset changes here } private native void onTextInputEventNative(State softKeyboardEvent); }أضِف
InputEnabledTextViewالذي تم إنشاؤه إلى تصميم واجهة المستخدم. على سبيل المثال، يمكن للرمز التالي فيactivity_main.xmlوضعه في أسفل الشاشة:<com.android.example.gametextinputjava.InputEnabledTextView android:id="@+id/input_enabled_text_view" android:layout_width="wrap_content" android:layout_height="wrap_content" app:layout_constraintBottom_toBottomOf="parent" app:layout_constraintEnd_toEndOf="parent" app:layout_constraintStart_toStartOf="parent" />استرِدّ مثيل
InputEnabledTextViewفي نشاط Java. هذا الأمر بسيط نسبيًا عند استخدام ربط العرض:public class MainActivity extends AppCompatActivity { ... private ActivityMainBinding binding; private InputEnabledTextView inputEnabledTextView; private native void setInputConnectionNative(InputConnection c); @Override protected void onCreate(Bundle savedInstanceState) { ... binding = ActivityMainBinding.inflate(getLayoutInflater()); inputEnabledTextView = binding.inputEnabledTextView; inputEnabledTextView.createInputConnection(InputType.TYPE_CLASS_TEXT); setInputConnectionNative(inputEnabledTextView.mInputConnection); }في مكتبة C، مرِّر
inputConnectionإلىGameTextInput_setInputConnection. يمكنك تمرير دالة رد اتصال فيGameTextInput_setEventCallbackليتم إعلامك بالأحداث كبنية حالة CGameTextInputState.extern "C"JNIEXPORT void JNICALL Java_com_gametextinput_testbed_MainActivity_setInputConnectionNative( JNIEnv *env, jobject this, jobject inputConnection) { GameTextInput_setInputConnection(gameTextInput, inputConnection); GameTextInput_setEventCallback(gameTextInput,[](void *ctx, const GameTexgtInputState *state) { if (!env || !state) return; // process the newly arrived text input from user. __android_log_print(ANDROID_LOG_INFO, "TheGreateGameTextInput", state->text_UTF8); }, env); }في مكتبة C، يمكنك استدعاء
GameTextInput_processEvent، التي تستدعي داخليًا دالة الاستدعاء المسجَّلة في الخطوة السابقة، لكي يتعامل تطبيقك مع الأحداث عند تغيُّر الحالة.extern "C" JNIEXPORT void JNICALL Java_com_gametextinput_testbed_InputEnabledTextView_onTextInputEventNative( JNIEnv* env, jobject this, jobject soft_keyboard_event) { GameTextInput_processEvent(gameTextInput, soft_keyboard_event); }
الدوال الخدمية
تتضمّن مكتبة GameTextInput دوال خدمية تتيح لك التحويل
بين عناصر حالة Java وبُنى حالة C. يمكنك الوصول إلى وظيفة إظهار
وإخفاء IME من خلال الدالتين GameTextInput_showIme
وGameTextInput_hideIme.
المراجع
قد يجد المطوّرون ما يلي مفيدًا عند إنشاء تطبيقات باستخدام
GameTextInput:
- تطبيق اختبار GameTextInput
- استخدام GameTextInput مع GameActivity
- مستند مرجعي حول GameTextInput
- الرمز المصدر لـ GameTextInput
الملاحظات
إذا واجهت أي مشاكل أو كانت لديك أسئلة حول GameTextInput، يمكنك إنشاء
خطأ في Google IssueTracker.