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

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

אם רוצים לאפשר למשתמשים להגדיר את ההגדרות של הווידג'ט, יוצרים הגדרת ווידג'ט 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>

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

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

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

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

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

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

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

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

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

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

   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>

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

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

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

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

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