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

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

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

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

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

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

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

  • ডিফল্ট হিসেবে, সিস্টেম একটি AppWidgetHostView তৈরি করে, কিন্তু হোস্ট এটিকে এক্সটেন্ড করে AppWidgetHostView-এর নিজস্ব সাবক্লাস তৈরি করতে পারে।
  • Android 12 (API লেভেল 31) থেকে শুরু করে, 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 উইজেট প্রদানকারীর সাথে যুক্ত অবজেক্ট থেকে।

সব হোস্টের নিম্নলিখিত দায়িত্ব থাকে:

• উইজেট যোগ করার সময়, আগে যেভাবে বর্ণনা করা হয়েছে সেইভাবে উইজেট আইডি অ্যাসাইন করুন। হোস্ট থেকে কোনও উইজেট সরিয়ে দেওয়া হলে, উইজেট ID deleteAppWidgetId() ডিলোক করার জন্য কল করুন।

• কোনও উইজেট যোগ করার সময়, কনফিগারেশন অ্যাক্টিভিটি লঞ্চ করার প্রয়োজন আছে কিনা তা চেক করে দেখুন। সাধারণত, হোস্টকে উইজেটের কনফিগারেশন অ্যাক্টিভিটি চালু করতে হবে, যদি সেটি থাকে এবং configuration_optional ও reconfigurable, দুটি ফ্ল্যাগই নির্দিষ্ট করে সেটিকে ঐচ্ছিক হিসেবে চিহ্নিত করা না থাকে। বিবরণের জন্য কনফিগারেশন অ্যাক্টিভিটি থেকে উইজেট আপডেট করুন লিঙ্কে দেখুন। অনেক উইজেট দেখানোর আগে এটি একটি প্রয়োজনীয় ধাপ।

• উইজেট AppWidgetProviderInfo মেটাডেটায় ডিফল্ট প্রস্থ ও দৈর্ঘ্য নির্দিষ্ট করে। এইসব ভ্যালু কোষে সংজ্ঞায়িত করা হয়—targetCellWidth ও targetCellHeight উল্লেখ করা থাকলে Android 12 থেকে শুরু করে—অথবা শুধুমাত্র minWidth ও minHeight উল্লেখ করা থাকলে dps। উইজেটের সাইজ সংক্রান্ত অ্যাট্রিবিউট দেখুন।

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

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

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

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

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

উইজেট যখন dps-এ maxResizeWidth ও maxResizeHeight অ্যাট্রিবিউট নির্দিষ্ট করে, তখন আমরা সাজেস্ট করি যে, কোনও উইজেট এই অ্যাট্রিবিউটগুলির মধ্যে অন্তত একটি ব্যবহার করলে, সেটি যেন অ্যাট্রিবিউট দ্বারা নির্দিষ্ট করা সাইজের থেকে বড় না হয়।

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

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