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

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

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

   KotlinJava

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

   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 पर सेट करें.

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

   KotlinJava

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

   int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(Activity.RESULT_CANCELED, resultValue);

3. उपयोगकर्ता की प्राथमिकताओं के हिसाब से विजेट को कॉन्फ़िगर करें.

4. कॉन्फ़िगरेशन पूरा होने के बाद, getInstance(Context) को कॉल करके AppWidgetManager का एक इंस्टेंस पाएं:

   KotlinJava

   val appWidgetManager = AppWidgetManager.getInstance(context)

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

5. विजेट को updateAppWidget(int,RemoteViews) को कॉल करके, RemoteViews लेआउट के साथ अपडेट करें:

   KotlinJava

   val views = RemoteViews(context.packageName, R.layout.example_appwidget)
   appWidgetManager.updateAppWidget(appWidgetId, views)

   RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
   appWidgetManager.updateAppWidget(appWidgetId, views);

6. सामान लौटाने का इंटेंट बनाएं, उसे गतिविधि के नतीजे के साथ सेट करें, और गतिविधि को पूरा करें:

   KotlinJava

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

   Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(RESULT_OK, resultValue);
   finish();

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

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

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

ध्यान दें: ये विकल्प सिर्फ़ Android 12 (एपीआई लेवल 31) से उपलब्ध हैं. इन्हें Android के पिछले वर्शन के लिए तय किया जा सकता है. हालांकि, सिस्टम इन पर ध्यान नहीं देता और डिफ़ॉल्ट तरीके से काम करता है.

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

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

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

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

पहली इमेज. विजेट फिर से कॉन्फ़िगर करें बटन.

ध्यान दें: reconfigurable फ़्लैग को Android 9 (एपीआई लेवल 28) में लॉन्च किया गया था. हालांकि, यह Android 12 तक बड़े पैमाने पर काम नहीं करता था.

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

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

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

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