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

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

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

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

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

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

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

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

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

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

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

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

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

अपने कॉन्टेंट को बेहतर बनाने के लिए सलाह

पिछले सेक्शन में बताई गई ज़रूरी शर्तों के अलावा, इन बातों का भी ध्यान रखें:

विकल्पों के बंडल में एक List<SizeF> हो सकता है. इसमें डीपी में उन संभावित साइज़ की सूची होती है जो विजेट के इंस्टेंस में हो सकते हैं. उपलब्ध कराए गए साइज़ की संख्या, होस्ट के लागू करने के तरीके पर निर्भर करती है. होस्ट आम तौर पर, फ़ोन के लिए दो साइज़ उपलब्ध कराते हैं: पोर्ट्रेट और लैंडस्केप. साथ ही, फ़ोल्ड किए जा सकने वाले डिवाइसों के लिए चार साइज़ उपलब्ध कराते हैं.

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

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

अन्य संसाधन

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