feat(input): a pen moves the pointer while hovering, clicks with its tip and right-clicks with its side button (#2625)

* feat(compositor): pen samples drive the pointer like a mouse

Input record 13 carries the pen's state (in proximity, tip, right and
middle button) and its position in input space as 24.8 fixed point.
Hover moves the pointer, the tip holds the left button, and a record
without the in-proximity bit releases every button. Under a pointer
lock only the buttons pass. A button pressed or released mid-stroke
keeps the implicit grab on the window the stroke started in, unless
that window closed.

* feat(input): a pen moves the pointer while hovering, clicks with its tip and right-clicks with its side button

In Mouse mode (the default) a pen's hover moves the pointer, the tip
holds the left button and the side button right-clicks; Touch keeps it a
finger. The side button can send a middle click or nothing instead, and
a Bluetooth pen key counts as the side button while the pen is near.
With glasses or a program's pointer lock the pen drives the touchpad.
A hover exit followed within 50 ms by more hover or a touch keeps the
pen near, so a pen at the edge of its hover range does not flicker out,
and a hover that sends nothing for 2 s leaves proximity. On the desktop
a pen that comes near releases KWin's grab of a hardware mouse, so the
pen moves KWin's pointer. Whatever cancels touches also ends the pen,
and stylus devices no longer count as hardware mice.

* feat(input): pen mode and side button settings in the Controls tab and the session drawer

A Pen group follows the touch settings once the phone has a stylus
device or a pen event was seen, which is remembered as penSeen and kept
by a settings reset. It holds Pen (Mouse, Touch) and Side button (Right
click, Middle click, Off); Side button is hidden in Touch. Before
Android 14 a touchscreen reports the stylus source without a pen, so
there it counts only with its first pen event. The strings are
translated into all 32 languages.

* docs: describe pen input and its limits

---------

Co-authored-by: alien2003 <11610652+alien2003@users.noreply.github.com>
This commit is contained in:
alien2003andalien2003 authored and GitHub committed 2026-11-15 09:38:01 -05:00
1 parent de70e37f30
commit decab6ea90
63 files changed
+2352 -38

No files matched your search

@@ -3,11 +3,16 @@ package com.droiddeck.launcher.input
object InputSpace {
const val WIDTH = 1920
const val HEIGHT = 1080
const val FIXED_ONE = 256
fun x(position: Float, viewWidth: Int): Int = scale(position, viewWidth, WIDTH)
fun y(position: Float, viewHeight: Int): Int = scale(position, viewHeight, HEIGHT)
fun fixedX(position: Float, viewWidth: Int): Int = scale(position, viewWidth, WIDTH * FIXED_ONE)
fun fixedY(position: Float, viewHeight: Int): Int = scale(position, viewHeight, HEIGHT * FIXED_ONE)
private fun scale(position: Float, extent: Int, size: Int): Int =
if (extent <= 0) 0 else (position / extent * size).toInt().coerceIn(0, size - 1)
}
@@ -0,0 +1,14 @@
package com.droiddeck.launcher.input
import com.droiddeck.launcher.session.SessionPrefs
object PenRouter {
enum class Route { BLOCKED, PEN, RELATIVE, TOUCH }
fun decide(uiBlocking: Boolean, mode: String, glasses: Boolean, programLock: Boolean): Route = when {
uiBlocking -> Route.BLOCKED
mode == SessionPrefs.PEN_TOUCH -> Route.TOUCH
glasses || programLock -> Route.RELATIVE
else -> Route.PEN
}
}
@@ -0,0 +1,247 @@
package com.droiddeck.launcher.input
import android.graphics.RectF
import android.os.Build
import android.os.Handler
import android.os.Looper
import android.os.SystemClock
import android.view.InputDevice
import android.view.KeyEvent
import android.view.MotionEvent
import com.droiddeck.launcher.session.SessionPrefs
class PenStream(private val sink: Sink) {
fun interface Sink {
fun sample(flags: Int, x: Int, y: Int)
}
private val handler = Handler(Looper.getMainLooper())
private val exitLater = Runnable { if (exitPending) leave() }
private val hoverWatchdog = Runnable { checkHover() }
private var watching = false
private var contact = false
private var barrel = 0
private var keyDown = false
private var keyDevice = Int.MIN_VALUE
private var keyCode = 0
private var exitPending = false
private var exitTime = 0L
private var deviceId = Int.MIN_VALUE
private var x = 0
private var y = 0
private var sampleTime = 0L
var sideButton = SessionPrefs.PEN_BUTTON_RIGHT
var inProximity = false
private set
fun onMotion(event: MotionEvent, pointer: Int, area: RectF, width: Int, height: Int): Boolean {
val action = event.actionMasked
val time = event.eventTime
val own = isPenAction(event, pointer)
expire(time)
when (action) {
MotionEvent.ACTION_HOVER_ENTER, MotionEvent.ACTION_HOVER_MOVE -> {
continueAt(time)
contact = false
enter(event)
samples(event, pointer, area, width, height)
}
MotionEvent.ACTION_HOVER_EXIT -> if (inProximity && !exitPending && !contact) pendExit(time)
MotionEvent.ACTION_BUTTON_PRESS, MotionEvent.ACTION_BUTTON_RELEASE -> {
continueAt(time)
if (!inProximity) return true
barrel = event.buttonState
samples(event, pointer, area, width, height)
}
MotionEvent.ACTION_DOWN, MotionEvent.ACTION_POINTER_DOWN -> if (own) {
continueAt(time)
enter(event)
contact = true
samples(event, pointer, area, width, height)
} else if (contact) samples(event, pointer, area, width, height)
MotionEvent.ACTION_MOVE -> if (contact) {
barrel = event.buttonState
samples(event, pointer, area, width, height)
}
MotionEvent.ACTION_UP, MotionEvent.ACTION_POINTER_UP -> if (!own) {
if (contact) samples(event, pointer, area, width, height)
} else if (contact) {
if (event.flags and MotionEvent.FLAG_CANCELED != 0) cancel()
else {
barrel = event.buttonState
samples(event, pointer, area, width, height, lift = true)
pendExit(time)
}
}
MotionEvent.ACTION_CANCEL -> cancel()
else -> return false
}
return true
}
fun onKey(event: KeyEvent): Boolean {
expire(event.eventTime)
val down = event.action == KeyEvent.ACTION_DOWN
val repeat = event.repeatCount > 0
if (exitPending && !repeat) leave()
if (!inProximity || exitPending) {
if (!repeat && event.deviceId == keyDevice && event.keyCode == keyCode) keyDown = down
return true
}
if (down == keyDown) return true
val before = state()
keyDown = down
if (down) {
keyDevice = event.deviceId
keyCode = event.keyCode
}
if (state() == before) return true
emit(state())
return true
}
fun cancel(releaseKey: Boolean = false) {
if (releaseKey) keyDown = false
leave()
}
fun holdsKey(event: KeyEvent): Boolean = keyDown && event.deviceId == keyDevice && event.keyCode == keyCode
fun deviceRemoved(deviceId: Int) {
if (deviceId == this.deviceId) cancel()
if (!keyDown || deviceId != keyDevice) return
val before = state()
keyDown = false
if (inProximity && state() != before) emit(state())
}
private fun enter(event: MotionEvent) {
barrel = event.buttonState
if (inProximity) return
inProximity = true
deviceId = event.deviceId
}
private fun continueAt(time: Long) {
if (!exitPending) return
if (time - exitTime > EXIT_GRACE_MS) { leave(); return }
exitPending = false
handler.removeCallbacks(exitLater)
}
private fun pendExit(time: Long) {
exitPending = true
exitTime = time
handler.removeCallbacks(exitLater)
handler.postDelayed(exitLater, EXIT_GRACE_MS)
}
private fun expire(time: Long) {
if (inProximity && !contact && time - sampleTime >= HOVER_TIMEOUT_MS) leave()
}
private fun watchHover(delay: Long = HOVER_TIMEOUT_MS) {
if (watching || contact) return
watching = true
handler.postDelayed(hoverWatchdog, delay)
}
private fun checkHover() {
watching = false
if (!inProximity || contact || exitPending) return
val silent = SystemClock.uptimeMillis() - sampleTime
if (silent >= HOVER_TIMEOUT_MS) leave() else watchHover(HOVER_TIMEOUT_MS - silent)
}
private fun leave() {
if (!inProximity) return
emit(0)
handler.removeCallbacks(exitLater)
handler.removeCallbacks(hoverWatchdog)
watching = false
inProximity = false
contact = false
exitPending = false
barrel = 0
}
private fun samples(event: MotionEvent, pointer: Int, area: RectF, width: Int, height: Int, lift: Boolean = false) {
for (h in 0 until event.historySize) sample(event, pointer, h, area, width, height)
if (lift) contact = false
sample(event, pointer, -1, area, width, height)
}
private fun sample(event: MotionEvent, pointer: Int, h: Int, area: RectF, width: Int, height: Int) {
x = InputSpace.fixedX(event.axis(MotionEvent.AXIS_X, pointer, h).coerceIn(area.left, area.right), width)
y = InputSpace.fixedY(event.axis(MotionEvent.AXIS_Y, pointer, h).coerceIn(area.top, area.bottom), height)
sampleTime = if (h < 0) event.eventTime else event.getHistoricalEventTime(h)
emit(state())
watchHover()
}
private fun emit(flags: Int) = sink.sample(flags, x, y)
private fun state(): Int =
PEN_IN or (if (contact) PEN_TIP else 0) or buttonFlags(keyDown || barrel and MotionEvent.BUTTON_STYLUS_PRIMARY != 0,
barrel and MotionEvent.BUTTON_STYLUS_SECONDARY != 0, sideButton)
private fun MotionEvent.axis(axis: Int, pointer: Int, h: Int): Float =
if (h < 0) getAxisValue(axis, pointer) else getHistoricalAxisValue(axis, pointer, h)
companion object {
const val PEN_IN = 1 shl 0
const val PEN_TIP = 1 shl 1
const val PEN_RIGHT = 1 shl 2
const val PEN_MIDDLE = 1 shl 3
const val HOVER_TIMEOUT_MS = 2_000L
const val EXIT_GRACE_MS = 50L
private val PEN_NAME = Regex("\\b(pen|stylus)", RegexOption.IGNORE_CASE)
fun isPen(event: MotionEvent, index: Int): Boolean = when (event.getToolType(index)) {
MotionEvent.TOOL_TYPE_STYLUS, MotionEvent.TOOL_TYPE_ERASER -> true
MotionEvent.TOOL_TYPE_UNKNOWN -> event.isFromSource(InputDevice.SOURCE_STYLUS)
else -> false
}
fun penConnected(): Boolean =
InputDevice.getDeviceIds().any { id -> InputDevice.getDevice(id)?.let { isPenDevice(it.sources) } == true }
// Before Android 14 a touchscreen that declares ABS_MT_TOOL_TYPE reports SOURCE_STYLUS without any pen.
fun isPenDevice(sources: Int, sdk: Int = Build.VERSION.SDK_INT): Boolean =
sources and InputDevice.SOURCE_STYLUS == InputDevice.SOURCE_STYLUS &&
(sources and InputDevice.SOURCE_TOUCHSCREEN != InputDevice.SOURCE_TOUCHSCREEN || sdk >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
fun penIndex(event: MotionEvent): Int {
for (index in 0 until event.pointerCount) if (isPen(event, index)) return index
return -1
}
fun isPenAction(event: MotionEvent, index: Int): Boolean = when (event.actionMasked) {
MotionEvent.ACTION_DOWN, MotionEvent.ACTION_UP, MotionEvent.ACTION_CANCEL -> true
MotionEvent.ACTION_POINTER_DOWN, MotionEvent.ACTION_POINTER_UP -> event.actionIndex == index
else -> false
}
fun isPenKey(event: KeyEvent): Boolean {
val device = event.device ?: return false
return isPenKeyboard(device.name, device.sources, Build.VERSION.SDK_INT < Build.VERSION_CODES.Q || device.isExternal,
device.keyboardType == InputDevice.KEYBOARD_TYPE_ALPHABETIC)
}
fun isPenKeyboard(name: String?, sources: Int, external: Boolean, alphabetic: Boolean): Boolean =
external && !alphabetic && sources == InputDevice.SOURCE_KEYBOARD && name != null && PEN_NAME.containsMatchIn(name)
fun buttonFlags(primary: Boolean, secondary: Boolean, sideButton: String): Int {
val first = when (sideButton) {
SessionPrefs.PEN_BUTTON_RIGHT -> PEN_RIGHT
SessionPrefs.PEN_BUTTON_MIDDLE -> PEN_MIDDLE
else -> 0
}
val second = if (sideButton == SessionPrefs.PEN_BUTTON_RIGHT) PEN_MIDDLE else PEN_RIGHT
return (if (primary) first else 0) or (if (secondary) second else 0)
}
}
}
@@ -23,13 +23,20 @@ internal fun MotionEvent.pointerSubset(pointerIdBits: Int): MotionEvent? {
}
val properties = Array(indices.size) { MotionEvent.PointerProperties() }
val coordinates = Array(indices.size) { MotionEvent.PointerCoords() }
indices.forEachIndexed { target, index ->
getPointerProperties(index, properties[target])
getPointerCoords(index, coordinates[target])
indices.forEachIndexed { target, index -> getPointerProperties(index, properties[target]) }
fun sample(position: Int): Array<MotionEvent.PointerCoords> {
indices.forEachIndexed { target, index ->
if (position < historySize) getHistoricalPointerCoords(index, position, coordinates[target])
else getPointerCoords(index, coordinates[target])
}
return coordinates
}
return MotionEvent.obtain(
downTime, eventTime, splitAction, indices.size, properties, coordinates,
fun time(position: Int) = if (position < historySize) getHistoricalEventTime(position) else eventTime
val split = MotionEvent.obtain(
downTime, time(0), splitAction, indices.size, properties, sample(0),
metaState, buttonState, xPrecision, yPrecision,
deviceId, edgeFlags, source, flags,
)
for (position in 1..historySize) split.addBatch(time(position), sample(position), metaState)
return split
}