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

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

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

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

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

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

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

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