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

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

अगर आपको उपयोगकर्ताओं को अपने विजेट की सेटिंग कॉन्फ़िगर करने की अनुमति देनी है, तो विजेट बनाएं कॉन्फ़िगरेशन 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 के तौर पर सेव होता है.
• सिस्टम Google को 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. विजेट को कॉल करने पर RemoteViews लेआउट updateAppWidget(int,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 सैंपल क्लास देखें.

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

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

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

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

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

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

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

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

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

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

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

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

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