विजेट होस्ट बनाएं

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

इस पेज पर, कस्टम AppWidgetHost को लागू करने से जुड़ी ज़िम्मेदारियों के बारे में बताया गया है. AppWidgetHost को लागू करने का तरीका जानने के लिए, Android की होम स्क्रीन के सोर्स कोड LauncherAppWidgetHost को देखें.

कस्टम AppWidgetHost को लागू करने में शामिल मुख्य क्लास और सिद्धांतों के बारे में खास जानकारी यहां दी गई है:

• ऐप्लिकेशन विजेट होस्ट: AppWidgetHost, उन ऐप्लिकेशन के लिए AppWidget सेवा के साथ इंटरैक्शन की सुविधा देता है जो अपने यूज़र इंटरफ़ेस (यूआई) में विजेट एम्बेड करते हैं. AppWidgetHost का आईडी, होस्ट के पैकेज में यूनीक होना चाहिए. यह आईडी, होस्ट के सभी इस्तेमाल के लिए बना रहता है. यह आईडी आम तौर पर एक हार्डकोड की गई वैल्यू होती है, जिसे आपको अपने ऐप्लिकेशन में असाइन करना होता है.

• ऐप्लिकेशन विजेट आईडी: हर विजेट इंस्टेंस को बाइंडिंग के समय एक यूनीक आईडी असाइन किया जाता है. bindAppWidgetIdIfAllowed() देखें. साथ ही, ज़्यादा जानकारी के लिए डेटा बाइंडिंग वाले विजेट सेक्शन देखें. होस्ट, allocateAppWidgetId() का इस्तेमाल करके यूनीक आईडी हासिल करता है. यह आईडी, विजेट के पूरे लाइफ़टाइम के लिए बना रहता है. इसे सिर्फ़ होस्ट से मिटाया जा सकता है. होस्ट से जुड़ी किसी भी स्थिति को होस्टिंग पैकेज के ज़रिए सेव किया जाना चाहिए. जैसे, विजेट का साइज़ और जगह. साथ ही, इसे ऐप्लिकेशन विजेट आईडी से जोड़ा जाना चाहिए.

• ऐप्लिकेशन विजेट होस्ट व्यू: AppWidgetHostView को एक फ़्रेम के तौर पर समझें. जब भी विजेट को दिखाया जाना होता है, तब उसे इस फ़्रेम में रैप किया जाता है. जब भी होस्ट, विजेट को बड़ा करता है, तो हर बार विजेट को AppWidgetHostView से जोड़ा जाता है.

  • डिफ़ॉल्ट रूप से, सिस्टम एक AppWidgetHostView बनाता है. हालांकि, होस्ट इसे बढ़ाकर AppWidgetHostView की अपनी सबक्लास बना सकता है.
  • Android 12 (एपीआई लेवल 31) से, AppWidgetHostView ने डाइनैमिक तरीके से ओवरलोड किए गए रंगों को मैनेज करने के लिए, setColorResources() और resetColorResources() तरीके पेश किए हैं. होस्ट की यह ज़िम्मेदारी है कि वह इन तरीकों के लिए रंग उपलब्ध कराए.

• विकल्पों का बंडल: AppWidgetHost, विकल्पों के बंडल का इस्तेमाल करके AppWidgetProvider को यह जानकारी देता है कि विजेट कैसे दिखाया जाता है. उदाहरण के लिए, साइज़ रेंज की सूची और विजेट लॉकस्क्रीन पर है या होम स्क्रीन पर. इस जानकारी से AppWidgetProvider को यह तय करने में मदद मिलती है कि विजेट का कॉन्टेंट और लुक कैसा होना चाहिए. यह इस बात पर निर्भर करता है कि विजेट को कैसे और कहां दिखाया जा रहा है. किसी विजेट के बंडल में बदलाव करने के लिए, updateAppWidgetOptions() और updateAppWidgetSize() का इस्तेमाल किया जा सकता है. इन दोनों तरीकों से, AppWidgetProvider के लिए onAppWidgetOptionsChanged() कॉलबैक ट्रिगर होता है.

विजेट बाइंड करना

जब कोई उपयोगकर्ता किसी होस्ट में कोई विजेट जोड़ता है, तो बाइंडिंग की प्रोसेस होती है. बाइंडिंग का मतलब है, किसी ऐप्लिकेशन विजेट आईडी को किसी खास होस्ट और किसी खास AppWidgetProvider से जोड़ना.

बाइंडिंग एपीआई की मदद से, होस्ट के लिए बाइंडिंग के लिए कस्टम यूज़र इंटरफ़ेस (यूआई) उपलब्ध कराना भी मुमकिन हो जाता है. इस प्रोसेस का इस्तेमाल करने के लिए, आपके ऐप्लिकेशन को होस्ट के मेनिफ़ेस्ट में BIND_APPWIDGET अनुमति का एलान करना होगा:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

हालांकि, यह तो सिर्फ़ पहला कदम है. रनटाइम के दौरान, उपयोगकर्ता को आपके ऐप्लिकेशन को साफ़ तौर पर अनुमति देनी होगी, ताकि वह होस्ट में विजेट जोड़ सके. यह जांचने के लिए कि आपके ऐप्लिकेशन के पास विजेट जोड़ने की अनुमति है या नहीं, bindAppWidgetIdIfAllowed() तरीके का इस्तेमाल करें. अगर bindAppWidgetIdIfAllowed(), false दिखाता है, तो आपके ऐप्लिकेशन को एक डायलॉग दिखाना होगा. इसमें उपयोगकर्ता से अनुमति देने के लिए कहा जाएगा: "अनुमति दें" का इस्तेमाल, मौजूदा विजेट को जोड़ने के लिए किया जाता है. वहीं, "हमेशा अनुमति दें" का इस्तेमाल, आने वाले समय में जोड़े जाने वाले सभी विजेट के लिए किया जाता है.

इस स्निपेट में, डायलॉग दिखाने का तरीका बताया गया है:

Kotlin

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Java

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

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

होस्ट की ज़िम्मेदारियां

AppWidgetProviderInfo मेटाडेटा का इस्तेमाल करके, विजेट के लिए कई कॉन्फ़िगरेशन सेटिंग तय की जा सकती हैं. इन कॉन्फ़िगरेशन विकल्पों को वापस पाया जा सकता है. इनके बारे में यहां दिए गए सेक्शन में ज़्यादा जानकारी दी गई है. इन्हें विजेट उपलब्ध कराने वाली कंपनी से जुड़े AppWidgetProviderInfo ऑब्जेक्ट से वापस पाया जा सकता है.

Android के जिस वर्शन को टारगेट किया जा रहा है उससे कोई फ़र्क़ नहीं पड़ता. सभी होस्ट की ये ज़िम्मेदारियां होती हैं:

• विजेट जोड़ते समय, विजेट आईडी को पहले बताए गए तरीके से असाइन करें. जब किसी विजेट को होस्ट से हटा दिया जाता है, तो विजेट आईडी को हटाने के लिए कॉल deleteAppWidgetId() करें.

• विजेट जोड़ते समय, देखें कि कॉन्फ़िगरेशन गतिविधि को लॉन्च करने की ज़रूरत है या नहीं. आम तौर पर, अगर विजेट का कॉन्फ़िगरेशन मौजूद है और configuration_optional और reconfigurable फ़्लैग सेट करके, उसे'ज़रूरी नहीं' के तौर पर मार्क नहीं किया गया है, तो होस्ट को विजेट का कॉन्फ़िगरेशन लॉन्च करना होगा. ज़्यादा जानकारी के लिए, कॉन्फ़िगरेशन गतिविधि से विजेट अपडेट करना लेख पढ़ें. यह कई विजेट के लिए ज़रूरी है, ताकि वे दिख सकें.

  ध्यान दें: उन मामलों को मैनेज करें जिनमें कॉन्फ़िगरेशन गतिविधि पूरी नहीं होती या गड़बड़ियों के साथ पूरी होती है.

• विजेट, AppWidgetProviderInfo मेटाडेटा में डिफ़ॉल्ट चौड़ाई और ऊंचाई तय करते हैं. इन वैल्यू को सेल में तय किया जाता है. Android 12 से शुरू होने वाले वर्शन में, अगर targetCellWidth और targetCellHeight तय किए गए हैं, तो सेल में वैल्यू तय की जाती है. अगर सिर्फ़ minWidth और minHeight तय किए गए हैं, तो डीपीआई में वैल्यू तय की जाती है. विजेट के साइज़ के एट्रिब्यूट देखें.

  पक्का करें कि विजेट को कम से कम इतने डीपी में लेआउट किया गया हो. उदाहरण के लिए, कई होस्ट आइकॉन और विजेट को ग्रिड में अलाइन करते हैं. इस मामले में, होस्ट डिफ़ॉल्ट रूप से ऐसे विजेट को जोड़ता है जिसमें कम से कम सेल का इस्तेमाल किया गया हो. साथ ही, minWidth और minHeight की शर्तों को पूरा किया गया हो.

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

टारगेट किए गए Android वर्शन के आधार पर, अपनी रणनीति तय करना

Android 12

Android 12 (एपीआई लेवल 31) में एक अतिरिक्त List<SizeF> बंडल किया गया है. इसमें dps में संभावित साइज़ की सूची होती है. यह सूची बताती है कि कोई विजेट इंस्टेंस, विकल्पों के बंडल में कितना साइज़ ले सकता है. उपलब्ध साइज़ की संख्या, होस्ट के लागू करने के तरीके पर निर्भर करती है. आम तौर पर, होस्ट किए जाने वाले ऐप्लिकेशन, फ़ोन के लिए दो साइज़ उपलब्ध कराते हैं—पोर्ट्रेट और लैंडस्केप. साथ ही, फ़ोल्ड किए जा सकने वाले डिवाइसों के लिए चार साइज़ उपलब्ध कराते हैं.

AppWidgetProvider, RemoteViews को ज़्यादा से ज़्यादा MAX_INIT_VIEW_COUNT (16) अलग-अलग तरह के RemoteViews दे सकता है. AppWidgetProvider ऑब्जेक्ट, List<SizeF> में मौजूद हर साइज़ के लिए RemoteViews ऑब्जेक्ट को मैप करते हैं. इसलिए, MAX_INIT_VIEW_COUNT से ज़्यादा साइज़ न दें.

Android 12 में, dps में maxResizeWidth और maxResizeHeight एट्रिब्यूट भी पेश किए गए हैं. हमारा सुझाव है कि कम से कम एक एट्रिब्यूट का इस्तेमाल करने वाला विजेट, एट्रिब्यूट के लिए तय की गई साइज़ की सीमा से ज़्यादा न हो.

अन्य संसाधन

• Glance रेफ़रंस दस्तावेज़ देखें.