দ্বিমাত্রিক স্ক্রলিং: scrollable2D, draggable2D

Jetpack Compose-এ, scrollable2D এবং draggable2D হল নিম্ন-স্তরের মডিফায়ার যা দুই মাত্রায় পয়েন্টার ইনপুট ম্যানেজ করার জন্য ডিজাইন করা হয়েছে। স্ট্যান্ডার্ড 1D মডিফায়ার scrollable এবং draggable একটি মাত্র ওরিয়েন্টেশনে সীমাবদ্ধ থাকলেও, 2D ভ্যারিয়েন্ট X এবং Y অক্ষ উভয় দিকেই একসাথে মুভমেন্ট ট্র্যাক করে।

যেমন, আগে থেকে থাকা scrollable মডিফায়ার সিঙ্গেল-ওরিয়েন্টেশন স্ক্রল ও ফ্লিং করার জন্য ব্যবহার করা হয়, যেখানে scrollable2d ব্যবহার করা হয় 2D-তে স্ক্রল ও ফ্লিং করার জন্য। এটি আপনাকে আরও জটিল লেআউট তৈরি করতে দেয় যা সব দিকে ঘোরে, যেমন স্প্রেডশিট বা ছবি দেখার টুল। scrollable2d মডিফায়ার 2D পরিস্থিতিতে নেস্টেড স্ক্রলিংয়ের ক্ষেত্রেও কাজ করে।

ছবি ১. ম্যাপে দুই দিকে প্যান করা।

scrollable2D বা draggable2D বেছে নিন

সঠিক API বেছে নেওয়া নির্ভর করে আপনি কোন UI এলিমেন্ট সরাতে চান এবং এই এলিমেন্টগুলির জন্য পছন্দের ফিজিক্যাল বিহেভিয়ারের উপর।

Modifier.scrollable2D: কন্টেনারের মধ্যে কন্টেন্ট সরানোর জন্য এই মডিফায়ার ব্যবহার করুন। যেমন, ম্যাপ, স্প্রেডশিট বা ফটো ভিউয়ারের সাথে এটি ব্যবহার করুন, যেখানে কন্টেনারের কন্টেন্ট অনুভূমিক ও উল্লম্ব, উভয় দিকেই স্ক্রল করতে হয়। এতে বিল্ট-ইন ফ্লিং সাপোর্ট অন্তর্ভুক্ত থাকে যাতে সোয়াইপ করার পরে কন্টেন্ট মুভ করতে থাকে এবং এটি পৃষ্ঠার অন্যান্য স্ক্রলিং কম্পোনেন্টের সাথে কোঅর্ডিনেট করে।

Modifier.draggable2D: কোনও কম্পোনেন্ট সরাতে এই মডিফায়ার ব্যবহার করুন। এটি একটি লাইটওয়েট মডিফায়ার, তাই ব্যবহারকারীর আঙুল থেমে গেলে ঠিক তখনই মুভমেন্ট থেমে যায়। এতে ফ্লিং সাপোর্ট অন্তর্ভুক্ত নেই।

আপনি যদি কোনও কম্পোনেন্ট ড্র্যাগেবল করতে চান, কিন্তু ফ্লিং বা নেস্টেড স্ক্রল সাপোর্টের প্রয়োজন না হয়, তাহলে draggable2D ব্যবহার করুন।

2D মডিফায়ার প্রয়োগ করুন

নিম্নলিখিত বিভাগে 2D মডিফায়ার কীভাবে ব্যবহার করতে হয় তার উদাহরণ দেওয়া আছে।

Modifier.scrollable2D প্রয়োগ করুন

কন্টেনারের জন্য এই মডিফায়ার ব্যবহার করুন যেখানে ব্যবহারকারীকে সব দিকে কন্টেন্ট সরাতে হবে।

টু-ডি মুভমেন্ট ডেটা ক্যাপচার করুন

এই উদাহরণে দেখানো হয়েছে কীভাবে প্রসেস না করা 2D মুভমেন্ট ডেটা ক্যাপচার করতে হয় এবং X,Y অফসেট দেখাতে হয়:

@Composable
private fun Scrollable2DSample() {
    // 1. Manually track the total distance the user has moved in both X and Y directions
    var offset by remember { mutableStateOf(Offset.Zero) }

    Box(
        modifier = Modifier
            .fillMaxSize()
            // ...
        contentAlignment = Alignment.Center
    ) {
        Box(
            modifier = Modifier
                .size(200.dp)
                // 2. Attach the 2D scroll logic to capture XY movement deltas
                .scrollable2D(
                    state = rememberScrollable2DState { delta ->
                        // 3. Update the cumulative offset state with the new movement delta
                        offset += delta

                        // Return the delta to indicate the entire movement was handled by this box
                        delta
                    }
                )
                // ...
            contentAlignment = Alignment.Center
        ) {
            Column(horizontalAlignment = Alignment.CenterHorizontally) {
                // 4. Display the current X and Y values from the offset state in real-time
                Text(
                    text = "X: ${offset.x.roundToInt()}",
                    // ...
                )
                Spacer(modifier = Modifier.height(8.dp))
                Text(
                    text = "Y: ${offset.y.roundToInt()}",
                    // ...
                )
            }
        }
    }
}

ছবি ২. একটি বেগুনি রঙের বক্স যা ব্যবহারকারী সারফেস জুড়ে পয়েন্টার ড্র্যাগ করার সময় বর্তমান X ও Y কোঅর্ডিনেট অফসেট ট্র্যাক করে ও দেখায়।

আগের স্নিপেট নিম্নলিখিত কাজ করে:

  • ব্যবহারকারী মোট কতটা স্ক্রল করেছেন তা offset-এ সেভ করা হয়।
  • rememberScrollable2DState-এর মধ্যে, ব্যবহারকারীর আঙুলের মাধ্যমে তৈরি হওয়া প্রতিটি ডেল্টা ম্যানেজ করার জন্য একটি ল্যাম্বডা ফাংশন সংজ্ঞায়িত করা হয়। offset.value += delta কোডটি নতুন পজিশন সহ ম্যানুয়াল স্টেট আপডেট করে।
  • Text কম্পোনেন্ট সেই offset স্ট্যাটের বর্তমান X ও Y ভ্যালু দেখায়, যা ব্যবহারকারী টেনে নিয়ে যাওয়ার সাথে সাথে রিয়েল-টাইমে আপডেট হয়।

বড় ভিউপোর্ট প্যান করুন

এই উদাহরণে দেখানো হয়েছে যে কীভাবে ক্যাপচার করা 2D স্ক্রলযোগ্য ডেটা ব্যবহার করতে হয় এবং translationX ও translationY এমন কন্টেন্টে প্রয়োগ করতে হয় যা তার পেরেন্ট কন্টেনারের থেকে বড়:

@Composable
private fun Panning2DImage() {

    // Manually track the total distance the user has moved in both X and Y directions
    val offset = remember { mutableStateOf(Offset.Zero) }

    // Define how gestures are captured. The lambda is called for every finger movement
    val scrollState = rememberScrollable2DState { delta ->
        offset.value += delta
        delta
    }

    // The Viewport (Container): A fixed-size box that acts as a window into the larger content
    Box(
        modifier = Modifier
            .size(600.dp, 400.dp) // The visible area dimensions
            // ...
            // Hide any parts of the large content that sit outside this container's boundaries
            .clipToBounds()
            // Apply the 2D scroll modifier to intercept touch and fling gestures in all directions
            .scrollable2D(state = scrollState),
        contentAlignment = Alignment.Center,
    ) {
        // The Content: An image given a much larger size than the container viewport
        Image(
            painter = painterResource(R.drawable.cheese_5),
            contentDescription = null,
            modifier = Modifier
                .requiredSize(1200.dp, 800.dp)
                // Manual Scroll Effect: Since scrollable2D doesn't move content automatically,
                // we use graphicsLayer to shift the drawing position based on the tracked offset.
                .graphicsLayer {
                    translationX = offset.value.x
                    translationY = offset.value.y
                },
            contentScale = ContentScale.FillBounds
        )
    }
}

ছবি ৩. Modifier.scrollable2D-এর মাধ্যমে তৈরি করা, একটি দ্বি-দিকনির্দেশক প্যানিং ইমেজ ভিউপোর্ট।
ছবি ৪. Modifier.scrollable2D-এর সাহায্যে তৈরি করা, দুই দিকে প্যানিং করা যায় এমন টেক্সট ভিউপোর্ট।

আগের স্নিপেটে নিম্নলিখিতগুলি অন্তর্ভুক্ত আছে:

  • কন্টেনারটি একটি নির্দিষ্ট সাইজে (600x400dp) সেট করা হয়েছে, যেখানে কন্টেন্টকে অনেক বড় সাইজ (1200x800dp) দেওয়া হয়েছে যাতে এটি তার মূল সাইজে ছোট বড় করা এড়ানো যায়।
  • কন্টেনারে clipToBounds() মডিফায়ার নিশ্চিত করে যে বড় কন্টেন্টের যে অংশ 600x400 বক্সের বাইরে আছে তা যেন দেখা না যায়।
  • LazyColumn-এর মতো হাই-লেভেল কম্পোনেন্টের মতো নয়, scrollable2D আপনার জন্য অটোমেটিক কন্টেন্ট সরিয়ে দেয় না। পরিবর্তে, আপনাকে graphicsLayer ট্রান্সফর্মেশন বা লেআউট অফসেট ব্যবহার করে আপনার কন্টেন্টে ট্র্যাক করা offset প্রয়োগ করতে হবে।
  • graphicsLayer ব্লকের মধ্যে, translationX = offset.value.x এবং translationY = offset.value.y আপনার আঙুলের মুভমেন্টের উপর ভিত্তি করে ছবি বা টেক্সটের ড্রয়িং পজিশন শিফট করে, স্ক্রল করার ভিজ্যুয়াল এফেক্ট তৈরি করে।

scrollable2D-এর সাহায্যে নেস্টেড স্ক্রলিং প্রয়োগ করুন

এই উদাহরণে দেখানো হয়েছে কীভাবে একটি দ্বি-দিকনির্দেশক কম্পোনেন্টকে একটি স্ট্যান্ডার্ড এক-দিকনির্দেশক পেরেন্ট কম্পোনেন্টে ইন্টিগ্রেট করা যায়, যেমন একটি উল্লম্ব নিউজ ফিড।

নেস্টেড স্ক্রলিং প্রয়োগ করার সময় নিম্নলিখিত বিষয়গুলি মনে রাখবেন:

  • rememberScrollable2DState-এর জন্য ল্যাম্বডা শুধুমাত্র ব্যবহৃত ডেল্টা রিটার্ন করবে, যাতে চাইল্ড তার সীমায় পৌঁছে গেলে পেরেন্ট লিস্ট স্বাভাবিকভাবে দায়িত্ব নিতে পারে।
  • ব্যবহারকারী আড়াআড়িভাবে ফ্লিং করলে, 2D গতিবেগ শেয়ার করা হয়। অ্যানিমেশন চলাকালীন বাচ্চাটি কোনও সীমানা স্পর্শ করলে, অবশিষ্ট মোমেন্টাম অভিভাবকের কাছে পৌঁছে যায় যাতে স্ক্রল করা স্বাভাবিকভাবে চলতে থাকে।

@Composable
private fun NestedScrollable2DSample() {
    var offset by remember { mutableStateOf(Offset.Zero) }
    val maxScrollDp = 250.dp
    val maxScrollPx = with(LocalDensity.current) { maxScrollDp.toPx() }

    Column(
        modifier = Modifier
            .fillMaxSize()
            .verticalScroll(rememberScrollState())
            .background(Color(0xFFF5F5F5)),
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        Text(
            "Scroll down to find the 2D Box",
            modifier = Modifier.padding(top = 100.dp, bottom = 500.dp),
            style = TextStyle(fontSize = 18.sp, color = Color.Gray)
        )

        // The Child: A 2D scrollable box with nested scroll coordination
        Box(
            modifier = Modifier
                .size(250.dp)
                .scrollable2D(
                    state = rememberScrollable2DState { delta ->
                        val oldOffset = offset

                        // Calculate new potential offset and clamp it to our boundaries
                        val newX = (oldOffset.x + delta.x).coerceIn(-maxScrollPx, maxScrollPx)
                        val newY = (oldOffset.y + delta.y).coerceIn(-maxScrollPx, maxScrollPx)

                        val newOffset = Offset(newX, newY)

                        // Calculate exactly how much was consumed by the child
                        val consumed = newOffset - oldOffset

                        offset = newOffset

                        // IMPORTANT: Return ONLY the consumed delta.
                        // The remaining (unconsumed) delta propagates to the parent Column.
                        consumed
                    }
                )
                // ...
            contentAlignment = Alignment.Center
        ) {
            Column(horizontalAlignment = Alignment.CenterHorizontally) {
                val density = LocalDensity.current
                Text("2D Panning Zone", color = Color.White.copy(alpha = 0.7f), fontSize = 12.sp)
                Spacer(Modifier.height(8.dp))
                Text("X: ${with(density) { offset.x.toDp().value.roundToInt() }}dp", color = Color.White, fontWeight = FontWeight.Bold)
                Text("Y: ${with(density) { offset.y.toDp().value.roundToInt() }}dp", color = Color.White, fontWeight = FontWeight.Bold)
            }
        }

        Text(
            "Once the Purple Box hits Y: 250 or -250,\nthis parent list will take over the vertical scroll.",
            textAlign = TextAlign.Center,
            modifier = Modifier.padding(top = 40.dp, bottom = 800.dp),
            style = TextStyle(fontSize = 14.sp, color = Color.Gray)
        )
    }
}

ছবি ৫. একটি উল্লম্ব স্ক্রলিং তালিকার মধ্যে একটি বেগুনি বক্স যা ইন্টার্নাল 2D মুভমেন্টের অনুমতি দেয়, কিন্তু বক্সের ইন্টার্নাল Y-অফসেট তার ৩০০-পিক্সেল সীমায় পৌঁছে গেলে পেরেন্ট তালিকায় উল্লম্ব স্ক্রল কন্ট্রোল পাস করে।

আগের স্নিপেটে:

  • 2D কম্পোনেন্ট ইন্টার্নালি প্যান করার জন্য X অক্ষের মুভমেন্ট ব্যবহার করতে পারে এবং একই সাথে চাইল্ডের নিজস্ব ভার্টিক্যাল বাউন্ডারিতে পৌঁছে গেলে পেরেন্ট লিস্টে Y অক্ষের মুভমেন্ট ডিসপ্যাচ করতে পারে।
  • ব্যবহারকারীকে 2D সারফেসে আটকে রাখার পরিবর্তে, সিস্টেমটি ব্যবহৃত ডেল্টা গণনা করে এবং বাকিটা হায়ারার্কিতে পাস করে। এর ফলে, ব্যবহারকারী আঙুল না তুলেই পৃষ্ঠার বাকি অংশ স্ক্রল করা চালিয়ে যেতে পারবেন।

Modifier.draggable2D প্রয়োগ করুন

Modifier.draggable2D কীভাবে ব্যবহার করবেন সেই সম্পর্কে তথ্যের জন্য, Modifier.draggable2D-এর সাহায্যে দুটি ডাইমেনশনে টেনে আনুন দেখুন।