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

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

אם רוצים לאפשר למשתמשים להגדיר את ההגדרות של הווידג'ט, צריך ליצור הגדרת ווידג'ט 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 כשמופעלת פעילות של הגדרה, כלומר היא לא קוראת ל-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="reconfigurable">
</appwidget-provider>

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

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

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

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

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