کاربران را قادر می سازد تا ویجت های برنامه را پیکربندی کنند

ویجت‌های برنامه قابل تنظیم هستند. برای مثال، یک ویجت ساعت می‌تواند به کاربران اجازه دهد منطقه زمانی مورد نظر خود را برای نمایش پیکربندی کنند.

اگر می‌خواهید به کاربران اجازه دهید تنظیمات ویجت شما را پیکربندی کنند، یک Activity پیکربندی ویجت ایجاد کنید. این activity به طور خودکار توسط میزبان ویجت برنامه، چه هنگام ایجاد ویجت و چه بعداً، بسته به گزینه‌های پیکربندی که مشخص می‌کنید، راه‌اندازی می‌شود.

فعالیت پیکربندی را اعلام کنید

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

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

اکتیویتی را در فایل AppWidgetProviderInfo.xml با استفاده از ویژگی android:configure تعریف کنید. برای اطلاعات بیشتر در مورد تعریف این فایل به اینجا مراجعه کنید. در اینجا مثالی از نحوه تعریف اکتیویتی پیکربندی آورده شده است:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

این فعالیت با یک فضای نام کاملاً واجد شرایط اعلام شده است، زیرا لانچر آن را از خارج از محدوده بسته شما ارجاع می‌دهد.

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

پیاده‌سازی فعالیت پیکربندی

دو نکته مهم وجود دارد که هنگام اجرای فعالیت باید به خاطر داشته باشید:

• میزبان ویجت برنامه، فعالیت پیکربندی را فراخوانی می‌کند و فعالیت پیکربندی باید همیشه یک نتیجه را برگرداند. نتیجه باید شامل شناسه ویجت برنامه باشد که توسط اینتنت ارسال شده و فعالیت را اجرا کرده است - که در فایل‌های اضافی اینتنت با عنوان EXTRA_APPWIDGET_ID ذخیره شده است.
• سیستم هنگام اجرای یک فعالیت پیکربندی، اعلان ACTION_APPWIDGET_UPDATE را ارسال نمی‌کند، به این معنی که هنگام ایجاد ویجت، متد onUpdate() را فراخوانی نمی‌کند. درخواست به‌روزرسانی از AppWidgetManager هنگام ایجاد ویجت برای اولین بار، بر عهده‌ی فعالیت پیکربندی است. با این حال، onUpdate() برای به‌روزرسانی‌های بعدی فراخوانی می‌شود - فقط بار اول نادیده گرفته می‌شود.

برای مثالی از نحوه‌ی برگرداندن نتیجه از پیکربندی و به‌روزرسانی ویجت، به قطعه کدهای موجود در بخش زیر مراجعه کنید.

ویجت را از فعالیت پیکربندی به‌روزرسانی کنید

وقتی یک ویجت از یک اکتیویتی پیکربندی استفاده می‌کند، مسئولیت به‌روزرسانی ویجت پس از تکمیل پیکربندی بر عهده‌ی اکتیویتی است. می‌توانید این کار را با درخواست به‌روزرسانی مستقیماً از AppWidgetManager انجام دهید.

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

1. شناسه ابزارک برنامه را از اینتنتی که اکتیویتی را اجرا کرده است، دریافت کنید:

   کاتلین

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID

   جاوا

   Intent intent = getIntent();
   Bundle extras = intent.getExtras();
   int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
   if (extras != null) {
       appWidgetId = extras.getInt(
               AppWidgetManager.EXTRA_APPWIDGET_ID,
               AppWidgetManager.INVALID_APPWIDGET_ID);
   }

2. نتیجه فعالیت را روی RESULT_CANCELED تنظیم کنید.

   به این ترتیب، اگر کاربر قبل از رسیدن به پایان از activity خارج شود، سیستم به میزبان ویجت برنامه اطلاع می‌دهد که پیکربندی لغو شده است و میزبان ویجت را اضافه نمی‌کند:

   کاتلین

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)

   جاوا

   int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(Activity.RESULT_CANCELED, resultValue);

3. ویجت را مطابق با تنظیمات برگزیده کاربر پیکربندی کنید.

4. وقتی پیکربندی کامل شد، با فراخوانی getInstance(Context) یک نمونه از AppWidgetManager دریافت کنید:

   کاتلین

   val appWidgetManager = AppWidgetManager.getInstance(context)

   جاوا

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

5. با فراخوانی updateAppWidget(int,RemoteViews) ویجت را با طرح‌بندی RemoteViews به‌روزرسانی کنید:

   کاتلین

   val views = RemoteViews(context.packageName, R.layout.example_appwidget)
   appWidgetManager.updateAppWidget(appWidgetId, views)

   جاوا

   RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
   appWidgetManager.updateAppWidget(appWidgetId, views);

6. هدف بازگشتی را ایجاد کنید، آن را با نتیجه فعالیت تنظیم کنید و فعالیت را پایان دهید:

   کاتلین

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()

   جاوا

   Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(RESULT_OK, resultValue);
   finish();

برای مثال به کلاس نمونه ListWidgetConfigureActivity.kt در GitHub مراجعه کنید.

گزینه‌های پیکربندی ویجت

به طور پیش‌فرض، میزبان ویجت برنامه فقط یک بار، بلافاصله پس از افزودن ویجت توسط کاربر به صفحه اصلی، فعالیت پیکربندی را اجرا می‌کند. با این حال، می‌توانید گزینه‌هایی را مشخص کنید که به شما امکان می‌دهد با ارائه پیکربندی پیش‌فرض ویجت، کاربران را قادر به پیکربندی مجدد ویجت‌های موجود یا صرف نظر کردن از پیکربندی اولیه ویجت کنید.

کاربران را قادر می‌سازد تا ابزارک‌های قرار داده شده را دوباره پیکربندی کنند

برای اینکه کاربران بتوانند ویجت‌های موجود را دوباره پیکربندی کنند، پرچم reconfigurable را در ویژگی widgetFeatures از appwidget-provider مشخص کنید. برای اطلاعات بیشتر به راهنمای اعلان فایل AppWidgetProviderInfo.xml مراجعه کنید. برای مثال:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

کاربران می‌توانند با لمس و نگه داشتن ویجت و زدن دکمه‌ی Reconfigure که در شکل ۱ با عدد ۱ مشخص شده است، ویجت خود را مجدداً پیکربندی کنند.

از تنظیمات پیش‌فرض ویجت استفاده کنید

شما می‌توانید با اجازه دادن به کاربران برای رد کردن مرحله پیکربندی اولیه، یک تجربه ویجت یکپارچه‌تر ارائه دهید. برای انجام این کار، هر دو پرچم configuration_optional و reconfigurable را در فیلد widgetFeatures مشخص کنید. این کار، اجرای فعالیت پیکربندی پس از افزودن ویجت توسط کاربر را حذف می‌کند. همانطور که قبلاً ذکر شد، کاربر همچنان می‌تواند ویجت را پس از آن دوباره پیکربندی کند . به عنوان مثال، یک ویجت ساعت می‌تواند پیکربندی اولیه را نادیده بگیرد و منطقه زمانی دستگاه را به طور پیش‌فرض نشان دهد.

در اینجا مثالی از نحوه علامت‌گذاری فعالیت پیکربندی خود به عنوان قابل پیکربندی مجدد و اختیاری آورده شده است:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>