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

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

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

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

• ऐप्लिकेशन विजेट होस्ट: AppWidgetHost, ऐप्लिकेशन विजेट सेवा के साथ इंटरैक्शन करता है. यह उन ऐप्लिकेशन के लिए होता है जो अपने यूज़र इंटरफ़ेस (यूआई) में विजेट एम्बेड करते हैं. 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 मेटाडेटा में डिफ़ॉल्ट चौड़ाई और ऊंचाई तय करते हैं. इन वैल्यू को सेल में तय किया जाता है. अगर targetCellWidth और targetCellHeight तय किए गए हैं, तो Android 12 से शुरू होने वाले वर्शन में ऐसा किया जाता है. अगर सिर्फ़ minWidth और minHeight तय किए गए हैं, तो डीपीआई में ऐसा किया जाता है. विजेट के साइज़ के एट्रिब्यूट देखें.

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

आपके तरीके के बारे में सलाह

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

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

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

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

अन्य संसाधन

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