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.

  1. اتّبِع التعليمات الواردة في صفحة ألعاب Jetpack Android لإضافة تبعية مكتبة 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، يجب تضمين ملف العنوان:

    #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، يمكنك إنشاء خطأ في Google IssueTracker.