অ্যাপ উইজেট কনফিগার করতে ব্যবহারকারীদের সক্ষম করুন

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

আপনি যদি ব্যবহারকারীদের আপনার উইজেটের সেটিংস কনফিগার করার সুযোগ দিতে চান, তাহলে একটি উইজেট কনফিগারেশন Activity তৈরি করুন। আপনার নির্দিষ্ট করা কনফিগারেশন অপশনগুলোর উপর নির্ভর করে, এই অ্যাক্টিভিটিটি উইজেট তৈরি হওয়ার সময় অথবা পরে অ্যাপ উইজেট হোস্ট দ্বারা স্বয়ংক্রিয়ভাবে চালু হয়।

কনফিগারেশন কার্যকলাপ ঘোষণা করুন

অ্যান্ড্রয়েড ম্যানিফেস্ট ফাইলে কনফিগারেশন অ্যাক্টিভিটিটিকে একটি সাধারণ অ্যাক্টিভিটি হিসেবে ঘোষণা করুন। অ্যাপ উইজেট হোস্ট এটিকে ACTION_APPWIDGET_CONFIGURE অ্যাকশন দিয়ে চালু করে, তাই অ্যাক্টিভিটিটিকে এই ইন্টেন্টটি গ্রহণ করতে হবে। উদাহরণস্বরূপ:

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

AppWidgetProviderInfo.xml ফাইলে android:configure অ্যাট্রিবিউট ব্যবহার করে অ্যাক্টিভিটিটি ডিক্লেয়ার করুন। এই ফাইলটি ডিক্লেয়ার করার বিষয়ে আরও তথ্য দেখুন। কনফিগারেশন অ্যাক্টিভিটি কীভাবে ডিক্লেয়ার করতে হয় তার একটি উদাহরণ নিচে দেওয়া হলো:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

অ্যাক্টিভিটিটি একটি সম্পূর্ণ যোগ্যতাসম্পন্ন নেমস্পেস দিয়ে ঘোষিত হয়, কারণ লঞ্চারটি আপনার প্যাকেজ স্কোপের বাইরে থেকে এটিকে রেফারেন্স করে।

একটি কনফিগারেশন কার্যক্রম শুরু করার জন্য এটুকুই যথেষ্ট। এরপর, আপনাকে প্রকৃত কার্যক্রমটি বাস্তবায়ন করতে হবে।

কনফিগারেশন কার্যকলাপ বাস্তবায়ন করুন

কার্যক্রমটি বাস্তবায়ন করার সময় দুটি গুরুত্বপূর্ণ বিষয় মনে রাখতে হবে:

• অ্যাপ উইজেট হোস্ট কনফিগারেশন অ্যাক্টিভিটিকে কল করে, এবং কনফিগারেশন অ্যাক্টিভিটিকে অবশ্যই সর্বদা একটি ফলাফল ফেরত দিতে হবে। যে ইন্টেন্টটি অ্যাক্টিভিটি চালু করেছে, সেই ইন্টেন্ট দ্বারা প্রেরিত অ্যাপ উইজেট আইডি-টি অবশ্যই ফলাফলের মধ্যে অন্তর্ভুক্ত থাকতে হবে, যা ইন্টেন্ট এক্সট্রাস-এ EXTRA_APPWIDGET_ID হিসাবে সংরক্ষিত থাকে।
  • যখন কোনো কনফিগারেশন অ্যাক্টিভিটি চালু করা হয়, তখন সিস্টেম ACTION_APPWIDGET_UPDATE ব্রডকাস্টটি পাঠায় না, যার মানে হলো উইজেটটি তৈরি করার সময় এটি প্রাথমিকভাবে আপনার উইজেট আপডেটগুলোকে কল করে না। প্রথমবার উইজেটটি তৈরি করার সময় GlanceAppWidget থেকে আপডেটের অনুরোধ করাটা কনফিগারেশন অ্যাক্টিভিটির দায়িত্ব। তবে, পরবর্তী চক্রগুলোর জন্য আপডেটগুলো স্বয়ংক্রিয়ভাবে চালু হয়ে যায়।

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

কনফিগারেশন অ্যাক্টিভিটি থেকে উইজেটটি আপডেট করুন।

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

উইজেটটি সঠিকভাবে আপডেট করতে এবং কনফিগারেশন অ্যাক্টিভিটিটি বন্ধ করতে যে পদ্ধতি অনুসরণ করতে হবে, তার একটি সারসংক্ষেপ নিচে দেওয়া হলো:

1. যে ইন্টেন্টটি অ্যাক্টিভিটিটি চালু করেছে, সেখান থেকে অ্যাপ উইজেট আইডিটি নিন:

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

2. অ্যাক্টিভিটির ফলাফল RESULT_CANCELED এ সেট করুন।

   এইভাবে, যদি ব্যবহারকারী শেষ পর্যায়ে পৌঁছানোর আগেই কাজটি থেকে বেরিয়ে যান, তাহলে সিস্টেম অ্যাপ উইজেট হোস্টকে জানিয়ে দেয় যে কনফিগারেশনটি বাতিল করা হয়েছে এবং হোস্ট উইজেটটি যোগ করে না:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

3. ব্যবহারকারীর পছন্দ অনুযায়ী উইজেটটি কনফিগার করুন, যেমন—নির্বাচিত তথ্যগুলো স্থায়ী ডেটাস্টোর বা স্থানীয় ডেটাবেসে লিখে রাখুন।

4. কনফিগারেশন সম্পূর্ণ হলে, প্ল্যাটফর্ম উইজেট আইডির সাথে সঙ্গতিপূর্ণ GlanceId সংগ্রহ করুন:

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. আপনার GlanceAppWidget ইনস্ট্যান্সে update suspend ফাংশনটি কল করে উইজেটের বিষয়বস্তু আপডেট করুন:

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. রিটার্ন ইন্টেন্টটি তৈরি করুন, অ্যাক্টিভিটির ফলাফল দিয়ে এটি সেট করুন এবং অ্যাক্টিভিটিটি শেষ করুন:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

উইজেট কনফিগারেশন বিকল্পগুলি

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

ব্যবহারকারীদের স্থাপন করা উইজেটগুলি পুনর্বিন্যাস করার সুযোগ দিন

ব্যবহারকারীদের বিদ্যমান উইজেটগুলি পুনর্বিন্যাস করার সুযোগ দিতে, appwidget-provider এর widgetFeatures অ্যাট্রিবিউটে reconfigurable ফ্ল্যাগটি উল্লেখ করুন। উদাহরণস্বরূপ:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

ব্যবহারকারীরা উইজেটটি স্পর্শ করে ধরে রেখে এবং চিত্র ১-এ ১ হিসাবে চিহ্নিত ‘পুনর্বিন্যাস’ বোতামটিতে ট্যাপ করে তাদের উইজেটটি পুনর্বিন্যাস করতে পারেন।

উইজেটের ডিফল্ট কনফিগারেশন ব্যবহার করুন

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

আপনার কনফিগারেশন অ্যাক্টিভিটিকে কীভাবে পুনঃকনফিগারযোগ্য এবং ঐচ্ছিক উভয় হিসাবে চিহ্নিত করবেন তার একটি উদাহরণ এখানে দেওয়া হলো:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>