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

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

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