إدخال نص اللعبة جزء من حزمة تطوير ألعاب Android.

يُعد استخدام مكتبة GameTextInput بديلاً أبسط لكتابة تطبيق Android بملء الشاشة يستخدم لوحة المفاتيح لإدخال النص.

توفّر GameTextInput واجهة برمجة تطبيقات واضحة لإظهار البيانات أو إخفاؤها لوحة المفاتيح، وضبط النص المعدَّل أو الحصول عليه، وتلقّي إشعارات عند يتم تغيير النص. وهذا ليس معنيًا بتطبيقات محرّر النصوص الكاملة، بل توفير دعم تحديد المنطقة وإنشائها لحالات الاستخدام النموذجية في الألعاب. تدعم هذه المكتبة أيضًا محرر أسلوب الإدخال المتقدم (IME) مثل التدقيق الإملائي التحقق واستكمالات الأحرف والأحرف متعددة المفاتيح.

داخليًا، ستعمل ميزة GameTextInput على تجميع النص المُدخَل (إلى جانب العلامة الولايات ذات الصلة) إلى المورد الاحتياطي الداخلي GameTextInput::currentState_ ويُبلغ التطبيق عن أي تغييرات تطرأ عليه. يُجري التطبيق بعد ذلك معالجة النصوص من خلال هي دالة معاودة الاتصال المسجلة.

مدى توفّر الخدمة

يمكن استخدام GameTextInput بالطرق التالية:

• مع GameActivity: GameActivity يتضمّن ميزة GameTextInput. يمكن للتطبيقات التي تستخدم GameActivity فقط استخدام GameTextInput. وقد تم توثيق تعليمات الاستخدام بالكامل على صفحة "نشاط الألعاب" . بالنسبة إلى كنموذج من دمج GameActivity وGameTextInput، راجِع مستودع نماذج الألعاب. نموذج الاستخدام هذا التي لا تندرج ضمن نطاق هذا الدليل.

• كمكتبة مستقلة: يصف باقي الدليل خطوات الاستخدام.

تجدر الإشارة إلى أنّ الطريقتَين أعلاه يستثنيان بعضهما البعض.

تتوفّر إصدارات GameTextInput الرسمية في القنوات التالية:

• إصدار مكتبة ألعاب Jetpack في Google Maven
• يتم إصدار ملف ZIP على صفحة تنزيل AGDK

يتناول هذا الدليل حالة الاستخدام الأولى. لاستخدام إصدارات ملف ZIP، يُرجى الرجوع إلى التعليمات التي يتم شحنها داخل الطرد.

إعداد تصميمك

يتم توزيع GameTextInput باعتباره أرشيف Android (AAR). يحتوي AAR هذا على فئات Java رمز المصدر C الذي ينفذ الميزات الأصلية لـ GameTextInput. إِنْتَ إلى تضمين ملفات المصدر هذه كجزء من عملية التصميم عبر Prefab، الذي يعرض المكتبات الأصلية ورمز المصدر في مشروع CMake أو إصدار NDK.

1. اتّبِع التعليمات الواردة في صفحة ألعاب Jetpack Android Games لإضافة GameTextInput اعتماد المكتبة لملف build.gradle الخاص باللعبة ملاحظة أنّه إذا كانت تطبيقاتك تستخدم GameActivity، فلا يمكنها استخدام مكتبة GameTextInput المستقلة.

2. تأكَّد من أنّ "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
   

3. عليك استيراد حزمة "game-text-input" وإضافتها إلى استهدافك في ملف CMakeLists.txt للمشروع:

   find_package(game-text-input REQUIRED CONFIG)
   ...
   target_link_libraries(... game-text-input::game-text-input)
   

4. في أحد الملفات البالغ عددها .cpp في لعبتك، أضِف السطر التالي لتضمينه تنفيذ GameTextInput:

   #include <game-text-input/gametextinput.cpp>
   

5. تضمين العنوان في الملفات المصدر التي تستخدم GameTextInput C API الملف:

   #include <game-text-input/gametextinput.h>
   

6. تجميع التطبيق وتشغيله. في حال حدوث أخطاء CMake، تحقَّق من AAR تمّ إعداد ملفات build.gradle بشكلٍ صحيح. إذا كان ملف #include لم يتم العثور عليه، يُرجى التحقق من ملف الإعداد CMakeLists.txt.

دمج تصميمك

1. من سلسلة محادثات 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);
       ...
   }
   

2. إنشاء صف في 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);
   }
   

3. أضِف 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" />
   

4. استرجع فئة 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);
     }
   

5. في مكتبة C، مرِّر inputConnection إلى GameTextInput_setInputConnection تمرير معاودة الاتصال خلال GameTextInput_setEventCallback أن يتم إشعارك بالأحداث على أنّها هيكل حالة C GameTextInputState.

   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);
   }
   

6. في مكتبة 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.