pythonnative 0.36.0__py3-none-any.whl → 0.37.0__py3-none-any.whl

pythonnative/templates/android_template/pythonnative/src/main/java/com/pythonnative/runtime/gestures/GestureArbiter.kt

@@ -0,0 +1,233 @@
+package com.pythonnative.runtime.gestures
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Turn a raw pointer-event stream into arbitrated gesture payloads.
+ *
+ * One arbiter serves one view. Positions are in the view's coordinate
+ * space (dp); times are seconds on any monotonic clock. Beyond running
+ * each gesture's state machine, the arbiter enforces the relationships
+ * serialized by Python:
+ *
+ * - Two gestures not in each other's `simultaneous` sets race; when
+ *   one activates, the other is force-failed for the interaction.
+ * - A gesture with a `wait_for` set may only activate after all of
+ *   those gestures have failed; its output is buffered meanwhile and
+ *   either flushed or discarded.
+ *
+ * This class is plain Kotlin (no Android types) so it is unit-testable
+ * with scripted pointer sequences.
+ */
+class GestureArbiter(specs: List<GestureConfig>, private val emitOut: EmitFn) {
+    private enum class State { POSSIBLE, WAITING, ACTIVE, DONE, FAILED }
+
+    private val pointers = LinkedHashMap<Int, Point>()
+    private val recognizers = ArrayList<Recognizer>()
+    private val indices = ArrayList<Int>()
+    private val sim = HashMap<Int, Set<Int>?>()
+    private val waitFor = HashMap<Int, Set<Int>>()
+    private val states = HashMap<Int, State>()
+    private val buffers = HashMap<Int, ArrayList<Map<String, Any?>>>()
+    private var lastT = 0.0
+
+    init {
+        specs.forEachIndexed { i, spec ->
+            val recognizer = Recognizer.create(i, spec) { index, payload -> mediate(index, payload) } ?: return@forEachIndexed
+            recognizers.add(recognizer)
+            indices.add(i)
+            sim[i] = spec.simultaneous
+            waitFor[i] = spec.waitFor
+            states[i] = State.POSSIBLE
+        }
+    }
+
+    // -- pointer input ---------------------------------------------------
+
+    /** Record a pointer press and advance every recognizer. */
+    fun pointerDown(pointerId: Int, x: Double, y: Double, t: Double) {
+        lastT = t
+        if (pointers.isEmpty() && states.values.none { it == State.WAITING }) {
+            for (i in indices) states[i] = State.POSSIBLE
+            buffers.clear()
+        }
+        pointers[pointerId] = Point(x, y)
+        for (r in recognizers) r.down(pointers, t)
+    }
+
+    /** Record pointer travel and advance every recognizer. */
+    fun pointerMove(pointerId: Int, x: Double, y: Double, t: Double) {
+        lastT = t
+        if (!pointers.containsKey(pointerId)) return
+        pointers[pointerId] = Point(x, y)
+        for (r in recognizers) r.move(pointers, t)
+    }
+
+    /** Record a pointer release and advance every recognizer. */
+    fun pointerUp(pointerId: Int, x: Double, y: Double, t: Double) {
+        lastT = t
+        pointers.remove(pointerId)
+        for (r in recognizers) r.up(pointers, t, x, y)
+    }
+
+    /** Abort every in-flight gesture (for example, touch stolen by a scroll parent). */
+    fun cancel(t: Double) {
+        lastT = t
+        pointers.clear()
+        buffers.clear()
+        for (i in indices) if (states[i] == State.WAITING) states[i] = State.FAILED
+        for (r in recognizers) r.cancel(t)
+    }
+
+    /** Advance time-based recognizers (long press, multi-tap windows). */
+    fun poll(t: Double) {
+        lastT = t
+        for (r in recognizers) r.poll(t)
+    }
+
+    /** Earliest time [poll] should be called, or `null`. */
+    fun nextDeadline(): Double? = recognizers.mapNotNull { it.deadline() }.minOrNull()
+
+    /** Whether a pan gesture is currently activated. */
+    fun hasActivePan(): Boolean = recognizers.any { it is PanRecognizer && it.active }
+
+    // -- arbitration -------------------------------------------------------
+
+    private fun recognizerFor(index: Int): Recognizer? = recognizers.firstOrNull { it.index == index }
+
+    private fun isSimultaneous(a: Int, b: Int): Boolean {
+        val simA = sim[a] ?: return true
+        val simB = sim[b] ?: return true
+        return b in simA && a in simB
+    }
+
+    private fun mediate(index: Int, payload: Map<String, Any?>) {
+        val state = payload["state"]
+        val current = states[index] ?: State.POSSIBLE
+        if (state == GestureState.FAILED) {
+            if (current == State.POSSIBLE || current == State.WAITING) setFailed(index)
+            return
+        }
+        when (current) {
+            State.FAILED -> return
+            State.ACTIVE -> {
+                emitOut(index, payload)
+                if (state == GestureState.ENDED) {
+                    states[index] = State.DONE
+                    onResolved(index, succeeded = true)
+                } else if (state == GestureState.CANCELLED) {
+                    states[index] = State.FAILED
+                    onResolved(index, succeeded = false)
+                }
+            }
+            State.WAITING -> buffers.getOrPut(index) { ArrayList() }.add(payload)
+            State.DONE -> {}
+            State.POSSIBLE -> requestActivation(index, payload)
+        }
+    }
+
+    private fun requestActivation(index: Int, payload: Map<String, Any?>) {
+        for (j in indices) {
+            if (j == index) continue
+            val s = states[j]
+            if ((s == State.ACTIVE || s == State.DONE) && !isSimultaneous(index, j)) {
+                setFailed(index)
+                return
+            }
+        }
+        val targets = (waitFor[index] ?: emptySet()).filter { states.containsKey(it) }
+        if (targets.any { states[it] == State.ACTIVE || states[it] == State.DONE }) {
+            setFailed(index)
+            return
+        }
+        if (targets.any { states[it] == State.POSSIBLE || states[it] == State.WAITING }) {
+            states[index] = State.WAITING
+            buffers.getOrPut(index) { ArrayList() }.add(payload)
+            return
+        }
+        activate(index, listOf(payload))
+    }
+
+    private fun activate(index: Int, payloads: List<Map<String, Any?>>) {
+        val last = payloads.lastOrNull()?.get("state")
+        val discreteDone = last == GestureState.ENDED || last == GestureState.CANCELLED
+        states[index] = if (discreteDone) State.DONE else State.ACTIVE
+        for (j in indices) {
+            if (j == index) continue
+            val s = states[j]
+            if ((s == State.POSSIBLE || s == State.WAITING) && !isSimultaneous(index, j)) {
+                recognizerFor(j)?.forceFail(lastT)
+                setFailed(j)
+            }
+        }
+        for (p in payloads) emitOut(index, p)
+        if (states[index] == State.DONE) onResolved(index, succeeded = true)
+    }
+
+    private fun setFailed(index: Int) {
+        if (states[index] == State.FAILED) return
+        states[index] = State.FAILED
+        buffers.remove(index)
+        onResolved(index, succeeded = false)
+    }
+
+    private fun onResolved(index: Int, succeeded: Boolean) {
+        for (waiter in indices) {
+            if (states[waiter] != State.WAITING) continue
+            val wf = waitFor[waiter] ?: emptySet()
+            if (index !in wf) continue
+            if (succeeded) {
+                recognizerFor(waiter)?.forceFail(lastT)
+                setFailed(waiter)
+                continue
+            }
+            val targets = wf.filter { states.containsKey(it) }
+            if (targets.any { states[it] == State.POSSIBLE || states[it] == State.WAITING }) continue
+            if (targets.any { states[it] == State.ACTIVE || states[it] == State.DONE }) {
+                recognizerFor(waiter)?.forceFail(lastT)
+                setFailed(waiter)
+                continue
+            }
+            val payloads = buffers.remove(waiter) ?: ArrayList()
+            states[waiter] = State.POSSIBLE
+            activate(waiter, payloads)
+        }
+    }
+
+    companion object {
+        /** Decode the serialized `gestures` prop (a JSON array of spec objects). */
+        fun decodeSpecs(specs: JSONArray?): List<GestureConfig> {
+            if (specs == null) return emptyList()
+            val out = ArrayList<GestureConfig>(specs.length())
+            for (i in 0 until specs.length()) {
+                val spec = specs.optJSONObject(i)
+                out.add(if (spec == null) GestureConfig(kind = "") else decodeSpec(spec))
+            }
+            return out
+        }
+
+        /** Decode one spec object. */
+        fun decodeSpec(spec: JSONObject): GestureConfig {
+            return GestureConfig(
+                kind = spec.optString("kind", ""),
+                nTaps = spec.optInt("n_taps", 1),
+                maxDistance = spec.optDouble("max_distance", 12.0),
+                minDurationMs = spec.optDouble("min_duration_ms", 500.0),
+                minDistance = spec.optDouble("min_distance", 10.0),
+                minPointers = spec.optInt("min_pointers", 1),
+                direction = spec.optString("direction", "any"),
+                minVelocity = spec.optDouble("min_velocity", 300.0),
+                nPointers = spec.optInt("n_pointers", 1),
+                simultaneous = spec.optJSONArray("simultaneous")?.let { intSet(it) },
+                waitFor = spec.optJSONArray("wait_for")?.let { intSet(it) } ?: emptySet(),
+            )
+        }
+
+        private fun intSet(array: JSONArray): Set<Int> {
+            val out = HashSet<Int>()
+            for (i in 0 until array.length()) out.add(array.optInt(i))
+            return out
+        }
+    }
+}

pythonnative/templates/android_template/pythonnative/src/main/java/com/pythonnative/runtime/gestures/GestureCoordinator.kt

@@ -0,0 +1,127 @@
+package com.pythonnative.runtime.gestures
+
+import android.annotation.SuppressLint
+import android.os.SystemClock
+import android.view.MotionEvent
+import android.view.View
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.bridge.JsonUtil
+import com.pythonnative.runtime.bridge.MainThread
+import com.pythonnative.runtime.bridge.PNLog
+import com.pythonnative.runtime.bridge.ViewRecord
+import com.pythonnative.runtime.components.PNEvents
+import com.pythonnative.runtime.components.ViewStyler
+import org.json.JSONArray
+import kotlin.math.max
+
+/**
+ * Binds `MotionEvent` streams on PythonNative views to a
+ * [GestureArbiter] and forwards its output as `gesture:<index>`
+ * events. Time-based deadlines (long press, multi-tap windows) are
+ * polled with the main `Handler`, scheduled at the arbiter's next
+ * deadline. When a pan activates, the parent is asked not to intercept
+ * so an enclosing scroll view can't steal the drag.
+ */
+object GestureCoordinator {
+    private const val KEY_ARBITER = "arbiter"
+    private const val KEY_BOUND = "gestures_bound"
+    private const val KEY_POLL_DEADLINE = "poll_deadline"
+    private const val KEY_POLL_TOKEN = "poll_token"
+
+    /** Install (or replace) the arbiter for `record` from its `gestures` prop value. */
+    fun bind(record: ViewRecord, specs: Any?) {
+        val state = record.state
+        val array = specs as? JSONArray
+        if (array == null || array.length() == 0) {
+            state[KEY_ARBITER] = null
+            return
+        }
+        val tag = record.tag
+        val arbiter = GestureArbiter(GestureArbiter.decodeSpecs(array)) { index, payload ->
+            PNEvents.fireTag(tag, "gesture:$index", JsonUtil.args(payload))
+        }
+        state[KEY_ARBITER] = arbiter
+        if (state[KEY_BOUND] == true) return
+        state[KEY_BOUND] = true
+        bindTouchStream(record)
+    }
+
+    /** Drop the arbiter and any pending poll for `record`. */
+    fun unbind(record: ViewRecord) {
+        record.state[KEY_ARBITER] = null
+        record.state[KEY_POLL_DEADLINE] = null
+        record.state[KEY_POLL_TOKEN] = ((record.state[KEY_POLL_TOKEN] as? Int) ?: 0) + 1
+    }
+
+    /** Whether `record` currently has gestures wired. */
+    fun hasArbiter(record: ViewRecord): Boolean = record.state[KEY_ARBITER] is GestureArbiter
+
+    @SuppressLint("ClickableViewAccessibility")
+    private fun bindTouchStream(record: ViewRecord) {
+        record.view.setOnTouchListener { v, event ->
+            if (ViewStyler.pointerEventsBlocked(v)) return@setOnTouchListener false
+            feed(record, event)
+        }
+    }
+
+    /**
+     * Translate one `MotionEvent` into arbiter pointer calls. Returns
+     * `true` while any gesture spec is wired (to keep receiving the
+     * stream), `false` when there is nothing to feed.
+     */
+    fun feed(record: ViewRecord, event: MotionEvent): Boolean {
+        val arbiter = record.state[KEY_ARBITER] as? GestureArbiter ?: return false
+        try {
+            val t = now()
+            val density = PNBridge.density()
+            when (event.actionMasked) {
+                MotionEvent.ACTION_DOWN, MotionEvent.ACTION_POINTER_DOWN -> {
+                    val idx = event.actionIndex
+                    arbiter.pointerDown(event.getPointerId(idx), (event.getX(idx) / density).toDouble(), (event.getY(idx) / density).toDouble(), t)
+                }
+                MotionEvent.ACTION_MOVE -> {
+                    for (i in 0 until event.pointerCount) {
+                        arbiter.pointerMove(event.getPointerId(i), (event.getX(i) / density).toDouble(), (event.getY(i) / density).toDouble(), t)
+                    }
+                    if (arbiter.hasActivePan()) record.view.parent?.requestDisallowInterceptTouchEvent(true)
+                }
+                MotionEvent.ACTION_UP, MotionEvent.ACTION_POINTER_UP -> {
+                    val idx = event.actionIndex
+                    arbiter.pointerUp(event.getPointerId(idx), (event.getX(idx) / density).toDouble(), (event.getY(idx) / density).toDouble(), t)
+                }
+                MotionEvent.ACTION_CANCEL -> arbiter.cancel(t)
+            }
+            schedulePoll(record)
+        } catch (e: Exception) {
+            PNLog.rateLimited("gesture-feed", "gesture feed failed", e)
+        }
+        return true
+    }
+
+    /** Seconds on the monotonic uptime clock. */
+    private fun now(): Double = SystemClock.uptimeMillis() / 1000.0
+
+    private fun schedulePoll(record: ViewRecord) {
+        val state = record.state
+        val arbiter = state[KEY_ARBITER] as? GestureArbiter ?: return
+        val deadline = arbiter.nextDeadline() ?: return
+        val pending = state[KEY_POLL_DEADLINE] as? Double
+        if (pending != null && pending <= deadline + 0.001) return
+        val delayMs = max(1L, ((deadline - now()) * 1000.0).toLong())
+        val token = ((state[KEY_POLL_TOKEN] as? Int) ?: 0) + 1
+        state[KEY_POLL_TOKEN] = token
+        state[KEY_POLL_DEADLINE] = deadline
+        MainThread.postDelayed({
+            if (state[KEY_POLL_TOKEN] == token) state[KEY_POLL_DEADLINE] = null
+            val live = state[KEY_ARBITER] as? GestureArbiter ?: return@postDelayed
+            live.poll(now())
+            schedulePoll(record)
+        }, delayMs)
+    }
+
+    /** Convenience for managers that own their own touch listener (Pressable). */
+    fun feed(view: View, event: MotionEvent): Boolean {
+        val record = PNBridge.registry.recordFor(view) ?: return false
+        return feed(record, event)
+    }
+}