উইজেট হোস্ট তৈরি করা

Android হোম স্ক্রিন, বেশিরভাগ Android-চালিত ডিভাইসে উপলভ্য, ব্যবহারকারীকে কন্টেন্টে দ্রুত অ্যাক্সেসের জন্য অ্যাপ উইজেট (বা উইজেট) এম্বেড করতে দেয়। আপনি যদি হোম স্ক্রিন রিপ্লেসমেন্ট বা একই ধরনের অ্যাপ তৈরি করেন, তাহলে AppWidgetHost প্রয়োগ করে ব্যবহারকারীকে উইজেট এম্বেড করার অনুমতি দিতে পারেন। বেশিরভাগ অ্যাপের ক্ষেত্রে এটি করার প্রয়োজন হয় না, তবে আপনি নিজের হোস্ট তৈরি করলে, হোস্টকে যে চুক্তিভিত্তিক আইনগত বাধ্যবাধকতা মেনে চলতে হয় তা বোঝা গুরুত্বপূর্ণ।

এই পৃষ্ঠায় কাস্টম AppWidgetHost প্রয়োগ করার সাথে জড়িত দায়িত্বের উপর ফোকাস করা হয়। AppWidgetHost কীভাবে প্রয়োগ করতে হয় তার নির্দিষ্ট উদাহরণ দেখতে, Android হোম স্ক্রিনের সোর্স কোড দেখুন LauncherAppWidgetHost।

কাস্টম AppWidgetHost প্রয়োগ করার ক্ষেত্রে মূল ক্লাস ও ধারণার ওভারভিউ এখানে দেওয়া হল:

• অ্যাপ উইজেট হোস্ট: AppWidgetHost সেইসব অ্যাপের জন্য AppWidget পরিষেবার সাথে ইন্টার‍্যাকশন প্রদান করে যেগুলি তাদের UI-তে উইজেট এম্বেড করে। AppWidgetHost-এর একটি আইডি থাকতে হবে যা হোস্টের নিজস্ব প্যাকেজের মধ্যে অনন্য। হোস্টের সব ব্যবহারের ক্ষেত্রে এই আইডি বজায় থাকে। আইডি সাধারণত একটি হার্ডকোড করা ভ্যালু যা আপনি আপনার অ্যাপে অ্যাসাইন করেন।

• অ্যাপ উইজেট আইডি: বাইন্ডিংয়ের সময় প্রতিটি উইজেট ইনস্ট্যান্সকে একটি অনন্য আইডি অ্যাসাইন করা হয়। bindAppWidgetIdIfAllowed() দেখুন এবং আরও বিবরণের জন্য, এর পরে থাকা বাইন্ডিং উইজেট বিভাগ দেখুন। হোস্ট allocateAppWidgetId() ব্যবহার করে অনন্য আইডি পায়। হোস্ট থেকে মুছে না দেওয়া পর্যন্ত এই আইডি উইজেটের লাইফটাইম জুড়ে থাকে। হোস্ট-নির্দিষ্ট যেকোনও স্টেট—যেমন উইজেটের সাইজ ও লোকেশন—হোস্টিং প্যাকেজের মাধ্যমে অবশ্যই বজায় রাখতে হবে এবং অ্যাপ উইজেট আইডির সাথে যুক্ত করতে হবে।

• অ্যাপ উইজেট হোস্ট ভিউ: AppWidgetHostView-কে একটি ফ্রেম হিসেবে ভাবুন যেখানে উইজেটটি দেখানোর প্রয়োজন হলেই সেটি ফ্রেমের মধ্যে দেখানো হয়। হোস্ট যখনই উইজেট ইনফ্লেট করে, তখনই উইজেটটি AppWidgetHostView-এর সাথে অ্যাসোসিয়েট করা হয়।

  • ডিফল্ট হিসেবে, সিস্টেম একটি AppWidgetHostView তৈরি করে, তবে হোস্ট AppWidgetHostView-এর নিজস্ব সাবক্লাস তৈরি করতে পারে।
  • Android ১২ (API লেভেল ৩১) থেকে শুরু করে, AppWidgetHostView ডায়নামিকভাবে ওভারলোড করা রঙ ম্যানেজ করার জন্য setColorResources() এবং resetColorResources() পদ্ধতি নিয়ে এসেছে। হোস্ট এই পদ্ধতিগুলিতে রঙ প্রদানের জন্য দায়ী।

• বিকল্পের বান্ডেল: AppWidgetHost বিকল্পের বান্ডেল ব্যবহার করে AppWidgetProvider-এর সাথে যোগাযোগ করে তথ্য প্রদান করে যে কীভাবে উইজেট দেখানো হবে—যেমন, সাইজ রেঞ্জের তালিকা—এবং উইজেটটি লকস্ক্রিন নাকি হোম স্ক্রিনে আছে। এই তথ্য AppWidgetProvider-কে উইজেটের কন্টেন্ট এবং এটি কীভাবে এবং কোথায় দেখানো হবে তার উপর ভিত্তি করে এর চেহারা কাস্টমাইজ করতে দেয়। আপনি updateAppWidgetOptions() এবং updateAppWidgetSize() ব্যবহার করে উইজেটের বান্ডেল পরিবর্তন করতে পারবেন। এই দুটি পদ্ধতিই AppWidgetProvider-এ onAppWidgetOptionsChanged() কলব্যাক ট্রিগার করে।

উইজেট বাইন্ডিং করা হচ্ছে

কোনও ব্যবহারকারী হোস্টে উইজেট যোগ করলে, বাইন্ডিং নামক একটি প্রসেস ঘটে। বাইন্ডিং বলতে নির্দিষ্ট হোস্ট এবং নির্দিষ্ট AppWidgetProvider-এর সাথে নির্দিষ্ট অ্যাপ উইজেট আইডি যুক্ত করাকে বোঝায়।

এছাড়াও, বাইন্ডিং API-এর সাহায্যে হোস্ট বাইন্ডিংয়ের জন্য কাস্টম UI প্রদান করতে পারে। এই প্রসেস ব্যবহার করতে, আপনার অ্যাপকে হোস্টের ম্যানিফেস্টে 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 ১২ থেকে শুরু করে, যদি targetCellWidth এবং targetCellHeight নির্দিষ্ট করা থাকে—অথবা ডিপি যদি শুধুমাত্র minWidth এবং minHeight নির্দিষ্ট করা থাকে। উইজেটের সাইজ সংক্রান্ত অ্যাট্রিবিউট দেখুন।

  নিশ্চিত করুন যে উইজেটটি অন্তত এই পরিমাণ ডিপি সহ লেআউট করা হয়েছে। যেমন, অনেক হোস্ট গ্রিডে আইকন ও উইজেট অ্যালাইন করে। এই পরিস্থিতিতে, ডিফল্ট হিসেবে হোস্ট এমন ন্যূনতম সংখ্যক সেল ব্যবহার করে উইজেট যোগ করে যা minWidth এবং minHeight সীমাবদ্ধতা পূরণ করে।

আপনার দৃষ্টিভঙ্গি সম্পর্কে পরামর্শ

আগের বিভাগে তালিকাভুক্ত প্রয়োজনীয়তা ছাড়াও, নিম্নলিখিত পরামর্শগুলি মনে রাখবেন:

বিকল্পের বান্ডেলে List<SizeF> থাকতে পারে, যাতে ডিপি-তে সম্ভাব্য সাইজের তালিকা থাকে, যা কোনও উইজেট ইনস্ট্যান্স নিতে পারে। কতগুলি সাইজ প্রদান করা হবে তা হোস্ট ইমপ্লিমেন্টেশনের উপর নির্ভর করে। হোস্ট সাধারণত ফোনের জন্য দুটি সাইজ —পোর্ট্রেট ও ল্যান্ডস্কেপ—এবং ফোল্ডেবল ডিভাইসের জন্য চারটি সাইজ প্রদান করে।

MAX_INIT_VIEW_COUNT (১৬)টি আলাদা RemoteViews-এর সীমা আছে যা AppWidgetProvider, RemoteViews-কে প্রদান করতে পারে। যেহেতু AppWidgetProvider অবজেক্ট RemoteViews অবজেক্টকে List<SizeF>-এর প্রতিটি সাইজের সাথে ম্যাপ করে, তাই MAX_INIT_VIEW_COUNT-এর বেশি সাইজ দেবেন না।

উইজেট ডিপি-তে maxResizeWidth এবং maxResizeHeight অ্যাট্রিবিউট নির্দিষ্ট করলে, আমরা সাজেস্ট করি যে এইসব অ্যাট্রিবিউটের মধ্যে অন্তত একটি ব্যবহার করে এমন উইজেট যেন অ্যাট্রিবিউট দ্বারা নির্দিষ্ট করা সাইজের বেশি না হয়।

অতিরিক্ত রিসোর্স

• Glance রেফারেন্স ডকুমেন্টেশন দেখুন।