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

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

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