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

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

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

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

מגדירים את פעילות ההגדרה כפעילות רגילה בקובץ המניפסט של Android. מארח הווידג'ט של האפליקציה מפעיל אותו באמצעות ACTION_APPWIDGET_CONFIGURE פעולה, ולכן הפעילות צריכה לקבל את הכוונה הזו. לדוגמה:

<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 בשידור חי כשמתבצעת פעילות של מערך הגדרות אישיות, כלומר לא להפעיל את ה-method 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>

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

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

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

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

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

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