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

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

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

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

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

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

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

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