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

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

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

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

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

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

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

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

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

विजेट को बांधना

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

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

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

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

Android 12

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

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

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

अन्य संसाधन

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