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

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

अगर आपको उपयोगकर्ताओं को अपने विजेट की सेटिंग कॉन्फ़िगर करने की अनुमति देनी है, तो विजेट कॉन्फ़िगरेशन 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 ब्रॉडकास्ट नहीं भेजता. इसका मतलब है कि विजेट बनने पर, यह शुरू में आपके विजेट के अपडेट को कॉल नहीं करता. पहली बार विजेट बनाते समय, GlanceAppWidget से अपडेट का अनुरोध करना, कॉन्फ़िगरेशन गतिविधि की ज़िम्मेदारी होती है. हालांकि, इसके बाद के साइकल के लिए, अपडेट अपने-आप ट्रिगर हो जाते हैं.

कॉन्फ़िगरेशन से नतीजा दिखाने और Glance विजेट को अपडेट करने के तरीके का उदाहरण देखने के लिए, अगले सेक्शन में दिए गए कोड स्निपेट देखें.

कॉन्फ़िगरेशन गतिविधि से विजेट को अपडेट करना

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

विजेट को सही तरीके से अपडेट करने और कॉन्फ़िगरेशन गतिविधि को बंद करने की प्रोसेस की खास जानकारी यहां दी गई है:

1. गतिविधि को लॉन्च करने वाले इंटेंट से, ऐप्लिकेशन विजेट आईडी पाएं:

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

2. गतिविधि के नतीजे को RESULT_CANCELED पर सेट करें.

   इस तरह, अगर उपयोगकर्ता गतिविधि के खत्म होने से पहले ही वापस चला जाता है, तो सिस्टम ऐप्लिकेशन विजेट होस्ट को सूचना देता है कि कॉन्फ़िगरेशन रद्द कर दिया गया है. साथ ही, होस्ट विजेट को नहीं जोड़ता:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

3. उपयोगकर्ता की प्राथमिकताओं के हिसाब से विजेट को कॉन्फ़िगर करें. उदाहरण के लिए, चुने गए विकल्पों को परसिस्टेंट डेटास्टोर या लोकल डेटाबेस में लिखें.

4. कॉन्फ़िगरेशन पूरा होने पर, प्लैटफ़ॉर्म विजेट आईडी के लिए GlanceId वापस पाएं:

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. अपने GlanceAppWidget इंस्टेंस पर update सस्पेंड फ़ंक्शन को कॉल करके, विजेट के कॉन्टेंट को अपडेट करें:

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. वापस जाने का इंटेंट बनाएं, इसे गतिविधि के नतीजे के साथ सेट करें, और गतिविधि खत्म करें:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

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

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

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

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

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

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

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

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

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

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