رد کف دست قلم

نماد امتیاز پنج ستاره

قلم می‌تواند ابزاری فوق‌العاده سازنده و خلاقانه باشد. اما وقتی کاربران با استفاده از قلم، نقاشی می‌کشند، می‌نویسند یا با یک برنامه تعامل می‌کنند، گاهی اوقات صفحه را با کف دست خود لمس می‌کنند. رویداد لمس می‌تواند قبل از اینکه سیستم آن را به عنوان لمس تصادفی کف دست تشخیص داده و رد کند، به برنامه شما گزارش شود.

بهترین شیوه‌ها

برنامه شما باید رویدادهای لمسی نامربوط را شناسایی کرده و آنها را نادیده بگیرد. در Jetpack Compose، می‌توانید از طریق PointerEvent به رویداد اصلی Android MotionEvent دسترسی پیدا کنید. MotionEvent برای ACTION_CANCEL بررسی کنید، که نشان می‌دهد یک حرکت باید متوقف شود و ممکن است نیاز به برگرداندن به حالت قبل داشته باشد. در اندروید ۱۳ (سطح API ۳۳) و بالاتر، پرچم FLAG_CANCELED را در رویدادهای ACTION_CANCEL و ACTION_POINTER_UP بررسی کنید، که سیگنال قوی مبنی بر غیرعمدی بودن لمس، مانند لمس کف دست، ارائه می‌دهد.

مواد لازم

  • Modifier.pointerInput() : اصلاح‌کننده‌ی Compose که برای پردازش ورودی اشاره‌گر استفاده می‌شود.
  • PointerEvent : نشان‌دهنده یک رویداد اشاره‌گر در Compose است که شامل یک یا چند تغییر است.
  • PointerEvent.motionEvent : ویژگی افزونه‌ای که دسترسی به MotionEvent زیربنایی اندروید (nullable) را فراهم می‌کند.
  • MotionEvent : رویدادهای لمسی و حرکتی را نشان می‌دهد. حاوی اطلاعات لازم برای تعیین اینکه آیا یک رویداد باید نادیده گرفته شود یا خیر.
  • ACTION_CANCEL : ثابت MotionEvent که نشان می‌دهد یک حرکت لغو شده است؛ حرکت باید متوقف شود و ممکن است نیاز به بازگشت به حالت اولیه داشته باشد.
  • ACTION_POINTER_UP : ثابت MotionEvent که نشان می‌دهد اشاره‌گری غیر از اشاره‌گر اول بالا رفته است (یعنی تماس با صفحه نمایش دستگاه را رها کرده است).
  • FLAG_CANCELED : ثابت MotionEvent که نشان می‌دهد بالا رفتن اشاره‌گر باعث یک رویداد لمس غیرعمدی شده است. به رویدادهای ACTION_POINTER_UP و ACTION_CANCEL در اندروید ۱۳ (سطح API ۳۳) و بالاتر اضافه شده است.

مراحل

اشیاء MotionEvent ارسال شده به برنامه خود را بررسی کنید. از API های MotionEvent برای تعیین ویژگی های رویداد استفاده کنید:

  • رویدادهای تک‌نشانگر - ACTION_CANCEL را بررسی کنید که نشان می‌دهد حرکت باید متوقف شود. در اندروید ۱۳ و بالاتر، FLAG_CANCELED را نیز بررسی کنید تا تأیید شود که لمس غیرعمدی بوده است.
  • رویدادهای چند اشاره‌گری - در اندروید ۱۳ و بالاتر، برای شناسایی لمس‌های غیرعمدی ACTION_POINTER_UP و FLAG_CANCELED را بررسی کنید.

با متوقف کردن حرکت و بازگرداندن هرگونه تغییر موقت، به این رویدادها پاسخ دهید.

۱. اشیاء رویداد حرکتی را بدست آورید

Modifier.pointerInput برای پردازش ورودی اشاره‌گر در یک Composable استفاده کنید. در محدوده ورودی اشاره‌گر، awaitPointerEventScope و awaitPointerEvent برای دریافت رویدادها استفاده کنید و MotionEvent اصلی اندروید را با استفاده از ویژگی motionEvent بازیابی کنید: 

import androidx.compose.ui.input.pointer.pointerInput
    Box(
        modifier = Modifier
            .fillMaxSize()
            .pointerInput(Unit) {
                awaitPointerEventScope {
                    while (true) {
                        val event = awaitPointerEvent()
                        val motionEvent = event.motionEvent
                        if (motionEvent != null) {
                            // Process motion event.
                        }
                    }
                }
            }
    )

۲. اقدام و پرچم‌های رویداد را تعیین کنید

MotionEvent برای ACTION_CANCEL بررسی کنید، که نشان دهنده یک رویداد تک اشاره‌گر در تمام سطوح API است. در اندروید ۱۳ و بالاتر، ACTION_POINTER_UP برای FLAG_CANCELED بررسی کنید: 

import androidx.compose.ui.input.pointer.pointerInput
    Box(
        modifier = Modifier
            .fillMaxSize()
            .pointerInput(Unit) {
                awaitPointerEventScope {
                    while (true) {
                        val event = awaitPointerEvent()
                        val motionEvent = event.motionEvent ?: continue

                        when (motionEvent.actionMasked) {
                            MotionEvent.ACTION_CANCEL -> {
                                // Process canceled single-pointer motion event for all SDK versions.
                            }
                            MotionEvent.ACTION_POINTER_UP -> {
                                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
                                    (motionEvent.flags and MotionEvent.FLAG_CANCELED) == MotionEvent.FLAG_CANCELED
                                ) {
                                    // Process canceled multi-pointer motion event for Android 13 and higher.
                                }
                            }
                        }
                    }
                }
            }
    )

۳. لغو حرکت

وقتی لمس کف دست را شناسایی کردید، می‌توانید اثرات روی صفحه نمایش آن حرکت را لغو کنید.

برنامه شما باید سابقه‌ای از اقدامات کاربر را نگه دارد تا ورودی‌های ناخواسته مانند لمس کف دست قابل لغو باشند. برای مثال، به بخش «پیاده‌سازی یک برنامه طراحی اولیه در پشتیبانی از قلم Enhance در یک آزمایشگاه کد برنامه اندروید» مراجعه کنید.

نتایج

برنامه شما اکنون می‌تواند لمس کف دست را برای رویدادهای چند اشاره‌گری در اندروید ۱۳ و سطوح API بالاتر و برای رویدادهای تک اشاره‌گری در تمام سطوح API شناسایی و رد کند.

منابع اضافی

برای اطلاعات بیشتر، به موارد زیر مراجعه کنید: