TextInput در GameActivity   بخشی از Android Game Development Kit.

GameActivity GameTextInput را با این روش‌ها ادغام می‌کند:

  • ارائه بسته‌بندی‌کننده
  • ایجاد پرچم برای دردسترس بودن رویداد ورودی نوشتار جدید
  • مستقیماً از میان‌گیر وضعیت GameTextInput برای محتوای نوشتاری استفاده می‌کند

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

alt_text

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

  • کنترل کردن صفحه‌کلید نرم‌افزاری در میانای کاربر
  • دانستن اینکه چه زمانی نوشتار جدید دردسترس است
  • بازیابی نوشتار ورودی کاربر و وضعیت‌های آن

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

کنترل کردن صفحه‌کلید نرم‌افزاری در میانای کاربر

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

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

alt_text

بررسی دردسترس بودن نوشتار

رویدادهای صفحه‌کلید نرم‌افزاری از GameTextInput در سمت Java به سمت 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_pollOnce(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_، جمع‌آوری می‌شوند. برنامه‌ها می‌توانند از یکی از روش‌های زیر برای بازیابی محتوای خود استفاده کنند:

  • میانای برنامه‌سازی کاربردی داده‌پوش GameActivity (توصیه‌شده)
  • GameTextInput API

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

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

  • تابع بازخوانی از نوع 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() مقداردهی اولیه کنند.

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

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

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

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

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

مرجع‌ها

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

بازخورد

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