המשתמשים יכולים להגדיר ווידג'טים של אפליקציות

אפשר להגדיר את הווידג'טים של האפליקציות. לדוגמה, בווידג'ט של שעון אפשר לאפשר למשתמשים להגדיר את אזור הזמן שיוצג.

אם רוצים לאפשר למשתמשים להגדיר את ההגדרות של הווידג'ט, צריך ליצור הגדרת ווידג'ט Activity. הפעילות הזו מופעלת אוטומטית על ידי מארח הווידג'ט של האפליקציה, בזמן יצירת הווידג'ט או מאוחר יותר, בהתאם לאפשרויות ההגדרה שאתם מציינים.

הצהרה על פעילות ההגדרה

מצהירים על פעילות ההגדרה כפעילות רגילה בקובץ המניפסט של Android. אפליקציית המארח של הווידג'ט מפעילה אותו באמצעות הפעולה ACTION_APPWIDGET_CONFIGURE, ולכן הפעילות צריכה לקבל את ה-Intent הזה. לדוגמה:

<activity android:name=".ExampleAppWidgetConfigurationActi>vity&<quot;
    int>ent-filte<r
        action android:name="android.appwidget.action.APPWID>GET_C<ONFIGURE">/<
    /int>ent-filter
/activity

מצהירים על הפעילות בקובץ AppWidgetProviderInfo.xml באמצעות המאפיין android:configure. מידע נוסף על הצהרה על הקובץ הזה דוגמה להצהרה על פעילות ההגדרה:

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

הפעילות מוצהרת עם מרחב שמות מלא, כי מפנה אליה מחוץ להיקף החבילה.

זה כל מה שצריך כדי להתחיל פעילות של הגדרת תצורה. לאחר מכן, צריך להטמיע את הפעילות בפועל.

הטמעה של פעילות ההגדרה

יש שני דברים חשובים שצריך לזכור כשמטמיעים את הפעילות:

• האפליקציה המארחת של הווידג'ט קוראת לפעילות ההגדרה, ופעילות ההגדרה תמיד צריכה להחזיר תוצאה. התוצאה חייבת לכלול את מזהה הווידג'ט של האפליקציה שהועבר על ידי ה-Intent שהפעיל את הפעילות – המזהה נשמר ב-Intent extras בתור EXTRA_APPWIDGET_ID.
• המערכת לא שולחת את השידור ACTION_APPWIDGET_UPDATE כשמופעלת פעילות של הגדרה, כלומר היא לא קוראת ל-method onUpdate() כשהווידג'ט נוצר. הפעילות של ההגדרה אחראית לבקש עדכון מ-AppWidgetManager כשיוצרים את הווידג'ט בפעם הראשונה. עם זאת, הפונקציה onUpdate() מופעלת בעדכונים הבאים – היא מושבתת רק בפעם הראשונה.

בקטעי הקוד שבקטע הבא יש דוגמה לאופן שבו מחזירים תוצאה מההגדרה ומעדכנים את הווידג'ט.

עדכון הווידג'ט מפעילות ההגדרה

כשבווידג'ט נעשה שימוש בפעילות הגדרה, הפעילות אחראית לעדכן את הווידג'ט כשההגדרה מסתיימת. כדי לעשות זאת, אפשר לבקש עדכון ישירות מAppWidgetManager.

ריכזנו כאן את השלבים לעדכון תקין של הווידג'ט ולסגירה של פעילות ההגדרה:

1. קבלת מזהה הווידג'ט של האפליקציה מה-Intent שהפעיל את הפעילות:

   Kotlin

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

   Java

   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.

   כך, אם המשתמש יוצא מהפעילות לפני שהוא מגיע לסוף, המערכת מודיעה למארח של הווידג'ט של האפליקציה שההגדרה בוטלה והמארח לא מוסיף את הווידג'ט:

   Kotlin

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

   Java

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

3. הגדרת הווידג'ט בהתאם להעדפות המשתמש.

4. בסיום ההגדרה, מקבלים מופע של AppWidgetManager על ידי קריאה ל-getInstance(Context):

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

5. כדי לעדכן את הווידג'ט עם פריסה של RemoteViews, קוראים לפונקציה updateAppWidget(int,RemoteViews):

   Kotlin

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

   Java

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

6. יוצרים את כוונת החזרה, מגדירים אותה עם תוצאת הפעילות ומסיימים את הפעילות:

   Kotlin

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

   Java

   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=">r<econfigurable">
/appwidget-provider

משתמשים יכולים להגדיר מחדש את הווידג'ט על ידי לחיצה ארוכה על הווידג'ט והקשה על הלחצן הגדרה מחדש, שמסומן ב-1 באיור 1.

שימוש בהגדרת ברירת המחדל של הווידג'ט

כדי לספק חוויית שימוש חלקה יותר בווידג'ט, אתם יכולים לאפשר למשתמשים לדלג על שלב ההגדרה הראשוני. כדי לעשות את זה, מציינים את הדגלים configuration_optional ו-reconfigurable בשדה widgetFeatures. כך נמנעת הפעלה של פעילות ההגדרה אחרי שמשתמש מוסיף את הווידג'ט. כמו שצוין קודם, המשתמש עדיין יכול להגדיר מחדש את הווידג'ט בהמשך. לדוגמה, ווידג'ט של שעון יכול לעקוף את ההגדרה הראשונית ולהציג כברירת מחדל את אזור הזמן של המכשיר.

דוגמה לאופן שבו אפשר לסמן את פעילות ההגדרה כפעילות שניתנת להגדרה מחדש וכפעילות אופציונלית:

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