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

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

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

    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 सैंपल क्लास देखें.

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

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

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

उपयोगकर्ताओं को मौजूदा विजेट को फिर से कॉन्फ़िगर करने की अनुमति देने के लिए, reconfigurable फ़्लैग को widgetFeatures के एट्रिब्यूट में तय करें appwidget-provider. ज़्यादा जानकारी के लिए, फ़ाइल की जानकारी देने से जुड़ा लेख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>