उपयोगकर्ताओं को ऐप्लिकेशन के विजेट कॉन्फ़िगर करने की सुविधा दें

ऐप्लिकेशन विजेट को कॉन्फ़िगर किया जा सकता है. उदाहरण के लिए, घड़ी का विजेट उपयोगकर्ताओं को यह कॉन्फ़िगर करने की सुविधा दे सकता है कि उन्हें कौन-सा टाइम ज़ोन दिखाना है.

अगर आपको उपयोगकर्ताओं को अपने विजेट की सेटिंग कॉन्फ़िगर करने की अनुमति देनी है, तो विजेट कॉन्फ़िगरेशन Activity बनाएं. यह गतिविधि, ऐप्लिकेशन विजेट होस्ट की मदद से अपने-आप लॉन्च होती है. ऐसा तब होता है, जब विजेट बनाया जाता है या बाद में, आपके बताए गए कॉन्फ़िगरेशन के विकल्पों के आधार पर.

कॉन्फ़िगरेशन गतिविधि का एलान करना

कॉन्फ़िगरेशन ऐक्टिविटी को Android मेनिफ़ेस्ट फ़ाइल में सामान्य ऐक्टिविटी के तौर पर तय करें. ऐप्लिकेशन विजेट होस्ट, इसे ACTION_APPWIDGET_CONFIGURE कार्रवाई के साथ लॉन्च करता है. इसलिए, गतिविधि को इस इंटेंट को स्वीकार करना होगा. उदाहरण के लिए:

<activity android:name=".ExampleAppWidgetConfigurationActi>vity&<quot;
    int>ent-filte<r
        action android:name="android.appwidget.action.APPWID>GET_C<ONFIGURE">/<
    /int>ent-filter
/activity

android:configure एट्रिब्यूट का इस्तेमाल करके, AppWidgetProviderInfo.xml फ़ाइल में गतिविधि के बारे में बताएं. इस फ़ाइल के बारे में जानकारी देने के बारे में ज़्यादा जानें. कॉन्फ़िगरेशन गतिविधि के बारे में बताने का तरीका यहां दिया गया है:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationAct>i<vity"
    ... >
/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. कॉन्फ़िगरेशन पूरा होने के बाद, getInstance(Context) को कॉल करके AppWidgetManager का इंस्टेंस पाएं:

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

5. updateAppWidget(int,RemoteViews) को कॉल करके, विजेट को 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();

उदाहरण के लिए, GitHub पर ListWidgetConfigureActivity.kt सैंपल क्लास देखें.

विजेट कॉन्फ़िगरेशन के विकल्प

डिफ़ॉल्ट रूप से, ऐप्लिकेशन विजेट होस्ट सिर्फ़ एक बार कॉन्फ़िगरेशन ऐक्टिविटी लॉन्च करता है. ऐसा तब होता है, जब उपयोगकर्ता विजेट को अपनी होम स्क्रीन पर जोड़ता है. हालांकि, ऐसे विकल्प तय किए जा सकते हैं जिनसे उपयोगकर्ताओं को मौजूदा विजेट को फिर से कॉन्फ़िगर करने की अनुमति दी जा सके. इसके अलावा, डिफ़ॉल्ट विजेट कॉन्फ़िगरेशन देकर, विजेट के शुरुआती कॉन्फ़िगरेशन को स्किप किया जा सकता है.

उपयोगकर्ताओं को, होम स्क्रीन पर रखे गए विजेट को फिर से कॉन्फ़िगर करने की अनुमति दें

उपयोगकर्ताओं को मौजूदा विजेट फिर से कॉन्फ़िगर करने की अनुमति देने के लिए, appwidget-provider एट्रिब्यूट के widgetFeatures एट्रिब्यूट में reconfigurable फ़्लैग तय करें. ज़्यादा जानकारी के लिए, AppWidgetProviderInfo.xml फ़ाइल का एलान करने से जुड़ी गाइड देखें. उदाहरण के लिए:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures=">r<econfigurable">
/appwidget-provider

उपयोगकर्ता, विजेट को फिर से कॉन्फ़िगर कर सकते हैं. इसके लिए, उन्हें विजेट को दबाकर रखना होगा. इसके बाद, फिर से कॉन्फ़िगर करें बटन पर टैप करना होगा. यह बटन, पहली इमेज में 1 के तौर पर दिखाया गया है.

विजेट के डिफ़ॉल्ट कॉन्फ़िगरेशन का इस्तेमाल करें

उपयोगकर्ताओं को बेहतर विजेट अनुभव देने के लिए, उन्हें शुरुआती कॉन्फ़िगरेशन के चरण को छोड़ने की अनुमति दें. इसके लिए, widgetFeatures फ़ील्ड में configuration_optional और reconfigurable, दोनों फ़्लैग की जानकारी दें. इससे उपयोगकर्ता के विजेट जोड़ने के बाद, कॉन्फ़िगरेशन गतिविधि शुरू नहीं होती. जैसा कि पहले बताया गया है, उपयोगकर्ता बाद में भी विजेट को फिर से कॉन्फ़िगर कर सकता है. उदाहरण के लिए, घड़ी का विजेट शुरुआती कॉन्फ़िगरेशन को बायपास कर सकता है और डिफ़ॉल्ट रूप से डिवाइस का टाइम ज़ोन दिखा सकता है.

यहां एक उदाहरण दिया गया है, जिसमें कॉन्फ़िगरेशन गतिविधि को फिर से कॉन्फ़िगर किया जा सकता है और उसे वैकल्पिक के तौर पर मार्क किया जा सकता है:

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