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

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

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

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

מצהירים על פעילות ההגדרה כפעילות רגילה בקובץ המניפסט של Android. המארח של הווידג'ט של האפליקציה מפעיל אותו באמצעות הפעולה 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>

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

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

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

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

• האפליקציה המארחת של הווידג'ט קוראת לפעילות ההגדרה, ופעילות ההגדרה תמיד צריכה להחזיר תוצאה. התוצאה חייבת לכלול את מזהה הווידג'ט של האפליקציה שהועבר על ידי ה-Intent שהפעיל את הפעילות – המזהה נשמר בתוספות של ה-Intent בתור EXTRA_APPWIDGET_ID.
• המערכת לא שולחת את השידור ACTION_APPWIDGET_UPDATE כשמופעלת פעילות של הגדרה, כלומר היא לא קוראת לשיטה 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="reconfigurable">
</appwidget-provider>

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

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

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

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

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