GameTextInput بخشی از کیت توسعه بازی اندروید .

استفاده از کتابخانه GameTextInput جایگزین ساده تری برای نوشتن یک برنامه اندروید تمام صفحه است که از صفحه کلید نرم برای ورودی متن استفاده می کند.

GameTextInput یک API ساده برای نمایش یا پنهان کردن صفحه کلید نرم، تنظیم یا دریافت متن ویرایش شده فعلی و دریافت اعلان ها هنگام تغییر متن ارائه می دهد. این برای برنامه‌های ویرایشگر متن کامل نیست، اما همچنان برای موارد استفاده معمولی در بازی‌ها، پشتیبانی منطقه انتخاب و نوشتن را فراهم می‌کند. همچنین، این کتابخانه از ویژگی های ویرایشگر روش ورودی پیشرفته (IME) مانند چک کردن املا، تکمیل ها و کاراکترهای چند کلیدی پشتیبانی می کند.

در داخل، GameTextInput متن ورودی را (به همراه حالت های مربوطه) در بافر داخلی GameTextInput::currentState_ جمع می کند و هر گونه تغییر در آن را به برنامه اطلاع می دهد. سپس برنامه پردازش متن را در عملکرد بازگشت به تماس ثبت شده خود انجام می دهد.

در دسترس بودن

GameTextInput می توان به روش های زیر استفاده کرد:

  • همراه با GameActivity: GameActivity GameTextInput را یکپارچه می کند. برنامه هایی که از GameActivity استفاده می کنند فقط می توانند از GameTextInput یکپارچه استفاده کنند. دستورالعمل های استفاده به طور کامل در صفحه GameActivity مستند شده است. برای نمونه‌ای از ادغام GameActivity و GameTextInput، به مخزن بازی-نمونه‌ها مراجعه کنید. این مدل استفاده در محدوده این راهنما نیست.

  • به عنوان یک کتابخانه مستقل: بقیه راهنما مراحل استفاده را شرح می دهد.

توجه داشته باشید که دو روش فوق متقابل هستند.

نسخه های رسمی GameTextInput در نسخه کتابخانه بازی های Jetpack در Google Maven موجود است.

ساخت خود را تنظیم کنید

GameTextInput به عنوان یک بایگانی Android (AAR) توزیع شده است. این AAR شامل کلاس‌های جاوا و کد منبع 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. یک کلاس جاوا 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 ایجاد شده را به طرح‌بندی UI اضافه کنید. به عنوان مثال، کد زیر در 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 را در فعالیت جاوا خود بازیابی کنید. وقتی از View Binding استفاده می‌کنید، این کار نسبتاً ساده است:

    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 شامل توابع ابزاری است که به شما امکان می دهد بین اشیاء حالت جاوا و ساختارهای حالت C تبدیل کنید. از طریق توابع GameTextInput_showIme و GameTextInput_hideIme به قابلیت نمایش و پنهان کردن IME دسترسی داشته باشید.

مراجع

برنامه‌نویسان ممکن است موارد زیر را هنگام ایجاد برنامه‌ها با GameTextInput مفید بدانند:

بازخورد

برای هر گونه مشکل و سؤال برای GameTextInput ، یک اشکال در Google IssueTracker ایجاد کنید.