একটি উইজেট হোস্ট তৈরি করুন

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

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

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

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

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

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

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

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

উইজেট বাইন্ডিং

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

বাইন্ডিং এপিআই একটি হোস্টকে বাইন্ডিংয়ের জন্য কাস্টম ইউআই প্রদান করার সুযোগও দেয়। এই প্রক্রিয়াটি ব্যবহার করার জন্য, আপনার অ্যাপকে অবশ্যই হোস্টের ম্যানিফেস্টে BIND_APPWIDGET পারমিশনটি ঘোষণা করতে হবে:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

কিন্তু এটি কেবল প্রথম ধাপ। রানটাইমে, হোস্টে একটি উইজেট যোগ করার জন্য ব্যবহারকারীকে অবশ্যই আপনার অ্যাপকে সুস্পষ্টভাবে অনুমতি দিতে হবে। আপনার অ্যাপের উইজেটটি যোগ করার অনুমতি আছে কিনা তা পরীক্ষা করতে, bindAppWidgetIdIfAllowed() মেথডটি ব্যবহার করুন। যদি bindAppWidgetIdIfAllowed() false রিটার্ন করে, তাহলে আপনার অ্যাপকে অবশ্যই একটি ডায়ালগ প্রদর্শন করতে হবে যা ব্যবহারকারীকে অনুমতি দেওয়ার জন্য অনুরোধ করবে: বর্তমান উইজেট যোগ করার জন্য "allow", অথবা ভবিষ্যতের সমস্ত উইজেট যোগ করার জন্য "always allow"।

এই কোড স্নিপেটটিতে ডায়ালগটি কীভাবে প্রদর্শন করতে হয় তার একটি উদাহরণ দেওয়া হয়েছে:

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)

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 অবজেক্ট থেকে পেতে পারেন।

আপনি অ্যান্ড্রয়েডের যে সংস্করণই ব্যবহার করুন না কেন, সকল হোস্টের নিম্নলিখিত দায়িত্বগুলো রয়েছে:

• উইজেট যোগ করার সময়, পূর্বে বর্ণিত পদ্ধতি অনুযায়ী উইজেট আইডি বরাদ্দ করুন। হোস্ট থেকে কোনো উইজেট সরিয়ে ফেলার সময়, উইজেট আইডি অবমুক্ত করতে deleteAppWidgetId() ফাংশনটি কল করুন।

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

• উইজেটগুলি AppWidgetProviderInfo মেটাডেটাতে একটি ডিফল্ট প্রস্থ এবং উচ্চতা নির্দিষ্ট করে। এই মানগুলি সেলগুলিতে সংজ্ঞায়িত করা হয়—অ্যান্ড্রয়েড ১২ থেকে শুরু করে, যদি targetCellWidth এবং targetCellHeight নির্দিষ্ট করা থাকে—অথবা dps-এ, যদি কেবল minWidth এবং minHeight নির্দিষ্ট করা থাকে। উইজেট সাইজিং অ্যাট্রিবিউটগুলি দেখুন।

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

পূর্ববর্তী বিভাগে তালিকাভুক্ত প্রয়োজনীয়তাগুলো ছাড়াও, প্ল্যাটফর্মের নির্দিষ্ট সংস্করণগুলো এমন কিছু বৈশিষ্ট্য যুক্ত করে যা হোস্টের উপর নতুন দায়িত্ব অর্পণ করে।

লক্ষ্যযুক্ত অ্যান্ড্রয়েড সংস্করণের উপর ভিত্তি করে আপনার পদ্ধতি নির্ধারণ করুন।

অ্যান্ড্রয়েড ১২

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

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

অ্যান্ড্রয়েড ১২-এ dps-এ maxResizeWidth এবং maxResizeHeight অ্যাট্রিবিউটও যুক্ত করা হয়েছে। আমাদের পরামর্শ হলো, যে উইজেট এই অ্যাট্রিবিউটগুলোর অন্তত একটি ব্যবহার করে, তার আকার যেন অ্যাট্রিবিউটগুলো দ্বারা নির্দিষ্ট করা আকার অতিক্রম না করে।

অতিরিক্ত সম্পদ

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