‫GameTextInput   جزء من حزمة تطوير البرامج (SDK) لألعاب Android

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

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

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

مدى التوفّر

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

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

  • كمكتبة مستقلة: يوضّح بقية الدليل خطوات الاستخدام.

يُرجى العِلم أنّ الطريقتَين أعلاه لا يمكن استخدامهما معًا.

تتوفّر إصدارات GameTextInput الرسمية في إصدار مكتبة ألعاب Jetpack ضمن Google Maven.

إعداد الإصدار

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

  1. اتّبِع التعليمات الواردة في صفحة ألعاب Android في Jetpack لإضافة تبعية مكتبة 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 المرفقة حاليًا بآلة Java الافتراضية (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. أنشئ InputEnabledTextView فئة Java يمكنها الوصول إلى 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.