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

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

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

कॉन्फ़िगरेशन गतिविधि के बारे में जानकारी देना

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

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

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

<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. उपयोगकर्ता की प्राथमिकताओं के हिसाब से विजेट को कॉन्फ़िगर करें. उदाहरण के लिए, चुने गए विकल्पों को परसिस्टेंट DataStore या लोकल डेटाबेस में लिखना.

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()
   

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

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

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

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

<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>