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

GameActivity یکپارچه سازی GameTextInput توسط:

  • ارائه یک لفاف
  • ایجاد یک پرچم برای در دسترس بودن رویداد ورودی متن جدید
  • مستقیماً از بافر حالت GameTextInput برای محتوای متن استفاده می کند

همانطور که در نمودار زیر نشان داده شده است، برنامه ها از اجزای منطقی داخلی مختلف برای هدف ورودی متن کاربر استفاده می کنند:

alt_text

سه مرحله کلی برای استفاده از کتابخانه داخلی GameTextInput وجود دارد:

  • کنترل صفحه کلید نرم روی رابط کاربری
  • دانستن زمانی که متن جدید در دسترس است
  • بازیابی متن ورودی کاربر و حالات آن

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

صفحه کلید نرم روی رابط کاربری را کنترل کنید

GameActivity دو عملکرد را برای کنترل صفحه کلید نرم روی رابط کاربری ارائه می دهد:

برای تعاریف آنها به اسناد مرجع API مراجعه کنید. پس از نمایش صفحه کلید، UI برنامه ممکن است شبیه به موارد زیر باشد:

alt_text

در دسترس بودن متن را بررسی کنید

رویدادهای صفحه کلید نرم از GameTextInput در سمت جاوا به سمت C/C++ از طریق JNI منتقل می‌شوند، سپس به پوشش GameActivity می‌روند و در نهایت در پرچم android_app::textInputState پیاده‌سازی شده در native_app_glue منعکس می‌شوند. برنامه ها باید این پرچم را به صورت دوره ای بررسی کنند تا پردازش مورد نظر را انجام دهند:

  • GameActivity فقط پرچم android_app::textInputState را تنظیم می کند.
  • برنامه ها پرچم را نظرسنجی می کنند و رویدادهای GameTextInput جدید را مدیریت می کنند، مانند متن جدیدی که به بافر ورودی اضافه شده است.
  • برنامه‌ها android_app::textInputState را پاک می‌کنند.

توجه داشته باشید که android_app::textInputState بین رویدادهای ورودی متنی تکی و چندگانه تفاوتی قائل نمی شود.

برای یک مثال ساده، کد زیر پرچم textInputState را پس از مدیریت فرمان‌های چرخه برنامه، رویدادهای لمسی و رویدادهای کلیدی نظرسنجی می‌کند: 

while (true) {
   // Read all pending events.
   int events;
   struct android_poll_source* source;

   while ((ALooper_pollAll(engine.animating ? 0 : -1, nullptr, &events,
                                 (void**)&source)) >= 0) {
       // Process this event, etc.
       ...
       // Check if we are exiting.
       if (app->destroyRequested != 0) {
           engine_term_display(&engine);
           return;
       }
   }
   engine_handle_input(app);

   // Process text input events if there is any outstanding.
   if (app->textInputState) {
       // process TextInput events.
          ...
       //reset the textInputState flag
       app->textInputState = 0;
   }
   if (engine.animating) {
         // draw frames.
   }
}

متن ورودی کاربر را بازیابی کنید

متون ورودی و سایر حالت ها در بافر داخلی GameTextInput، GameTextInput::currentState_ انباشته می شوند. برنامه ها می توانند از یکی از راه های زیر برای بازیابی محتوای خود استفاده کنند:

  • API wrapper GameActivity (توصیه می شود)
  • GameTextInput API

با GameActivity API وضعیت TextInput را دریافت کنید

برنامه‌ها ورودی متن فعلی را با مکانیسم برگشت تماس معمولی دریافت می‌کنند:

  • برای پردازش رویدادهای ورودی متن، یک تابع تماس از نوع GameTextInputGetStateCallback را اجرا کنید.
  • هنگامی که یک یا چند رویداد برجسته وجود دارد، GameActivity_getInputState() را فراخوانی کنید.
  • پس از پردازش رویدادها، android_app::textInputState پاک کنید.

با ادامه قطعه در بخش قبل، کد زیر یک مرجع به بافر ورودی متن دریافت می‌کند، آن را پردازش می‌کند (نمایش داده نمی‌شود)، و پرچم رویداد را بازنشانی می‌کند:

extern "C" void GameTextInputGetStateCB(void *ctx, const struct GameTextInputState *state) {
    auto* engine = (struct engine*)ctx;
    if (!engine || !state) return;

    // Process the text event(s).
    LOGI("UserInputText: %s", state->text_UTF8);

    // Clear the text input flag.
    engine->app->textInputState = 0;
}

در حلقه بازی نشان داده شده در بخش قبل، متن را با کنترل کننده ورودی متن بالا بررسی و پردازش کنید:

if (state->textInputState) {
    GameActivity_getTextInputState(
        app->activity,
        GameTextInputGetStateCB,  // App's event handler shown above.
        &engine // Context to the GameTextInputGetStateCB function.
    );
}

برنامه ها می توانند به صورت اختیاری محتوای GameTextInputState را با GameActivity_setTextInputState() مقداردهی اولیه کنند.

با GameTextInput API وضعیت TextInput را دریافت کنید

برنامه‌ها همچنین می‌توانند مستقیماً از GameTextInput API برای بازیابی GameTextInputState فعلی استفاده کنند:

  • از GameActivity_getTextInput() برای دریافت نمونه GameTextInput داخلی GameActivity استفاده کنید.
  • با در دست داشتن نمونه GameTextInput ، GameTextInput_getState() را فراخوانی کنید تا همان محتوای GameTextInputState را دریافت کنید.

مجدداً، توجه داشته باشید که برنامه‌ها نباید GameTextInput مستقیماً مقداردهی اولیه کنند. GameActivity قبلاً این کار را در طول فرآیند اولیه سازی خود انجام می دهد.

مکانیسم برگشت تماس همان چیزی است که توسط تابع GameActivity_getTextInputState() GameActivity استفاده می شود.

مراجع

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

بازخورد

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