多点输入

核心契约:统一指针输入、Root 路由与组件自身回调。不改 GPU 绘制接口,不保留两套 mouse/touch API。原生来源能力由各后端提供,假输入测试不代表真实硬件验收。

核心边界

Root 统一选择目标、转换坐标、分发和管理生命周期;组件回调只处理自身。树与几何由 visitInput 报告。定向投递也解析完整祖先路径,不能裸调用叶子绕过 scissor、变换或虚拟化。

独占归属为 PointerId → DslId。不同指针可分别捕获控件,同控件可接纳多个指针;不长期保存每帧重建的 owner 对象,不增加 Capture.press。同鼠标所有按钮共用一个独占者,明确舍弃“左键捕获 A、右键同时捕获 B”。按钮仍分别产生 Down/Up,事件带完整按住集合。

协议公开面仅增加指针身份、设备/按钮枚举、事件、无载荷结果和遍历协议;不增加 sample/buttons 包装、捕获记录或手势仲裁器。取消统一为 PointerEvent.Cancel,批量取消循环提交,不增加公开 capture/cancel/pointerInputTo 同义入口。

指针类型与字段

@JvmInline
value class PointerId(val value: Long)

enum class PointerKind { MOUSE, TOUCH, PEN }
enum class PointerButton {
    PRIMARY, SECONDARY, AUXILIARY, BUTTON4, BUTTON5, BUTTON6, BUTTON7
}
enum class PointerResult { IGNORED, HANDLED, TRACK, CAPTURE }

PointerEvent 是 sealed interface,只声明 val id: PointerId;下面五个变体是其嵌套 data class。字段顺序、默认值按表定义,Down/Up 的 button 放在 position 后;不另设公开位置事件中间类型。

变体 字段
Down id、kind、position、button、buttons、canHover、modifiers、pressure
Move id、kind、position、buttons、canHover、modifiers、pressure
Up id、kind、position、button、buttons、canHover、modifiers、pressure
Cancel id
Leave id
字段 类型、默认值与契约
id PointerId,必填;Root 内全部设备来源共用身份分配,旧事件排空前不复用,不使用触点数组下标
kind PointerKind,必填;同一身份期间稳定
position Position,必填且有限;入口为输出目标像素,组件收到当前节点局部坐标;局部并非相对 rect 左上角,仍可直接与自身 rect 比较
button PointerButton,必填;本次变化的按钮
buttons Set,必填;变化后的完整快照,Root 在接收时冻结/复制,不能长期引用调用者可变 Set
canHover Boolean,必填;无按钮/接触时继续报告位置的能力,同一身份期间稳定,不能由 kind 代替
modifiers KeyModifiers,默认 KeyModifiers()
pressure Float,默认 if (buttons.isEmpty()) 0f else 0.5f;有限且在 0f..1f,表示归一化压力

Down 的 button 必须从未按住变为按住,Up 从按住变为未按住,Move 不改变 buttons。最终 Up 是 buttons 为空,必须包含最终位置,不能沿用最后 Move。每根 TOUCH 使用独立 id 和 PRIMARY。可悬停 PEN 从悬停、笔尖接触到抬起返回悬停保持 id;笔尖为 PRIMARY,侧键为其它逻辑按钮。首批不表达橡皮端、倾角、历史样本和时间戳。

适配器按量程归一化 pressure。不支持压感时按住为 0.5,否则为 0,采用 W3C Pointer Events 压力约定;不增加 hasPressure,不能通过值恰为 0.5 判断设备能力。buttons 为空时 pressure 为 0;真实压感设备侧键按住而笔尖悬空也可为 0。非最终 Up 保留变化后的真实压力,松开侧键不强制归零。

生命周期只由 Down/Up/buttons 表达,不从 pressure 推断。原地压力变化也提交 Move,Root 不能按位置相同丢弃;变换不改变压力。Cancel/Leave 不伪造位置、设备或压力样本。

每层接口

以下定义输入相关的完整回调;保留 DslComponent 其它布局、元数据、导航成员。onPointer 是普通成员函数,默认 IGNORED,不检测是否覆写,不增加可空函数属性或 pointerEnabled 标志。

interface DslComponentEvent {
    context(backend: DslRootRenderer<RP>, renderParam: RP)
    fun <RP> render() {}

    fun onPointer(event: PointerEvent): PointerResult = PointerResult.IGNORED

    context(eventModifier: KeyModifiers)
    fun keyDown(key: Key, scanCode: Int): Boolean = false
    context(eventModifier: KeyModifiers)
    fun keyUp(key: Key, scanCode: Int): Boolean = false
    fun charTyped(c: Char): Boolean = false
    fun preedit(info: PreeditInfo) {}

    context(position: Position)
    fun mouseScrollVertical(amount: Double): Double = amount
    context(position: Position)
    fun mouseScrollHorizontal(amount: Double): Double = amount
    context(position: Position)
    fun dropFiles(files: Array<Path>): Boolean = false
}

interface DslComponentGlobalEvent {
    fun globalFocusChanged(newFocus: DslId?, source: FocusSource) {}
    fun globalHoverChanged(pointerId: PointerId, newHover: DslId?) {}
}

// 现有 DslComponent 中新增的成员。
interface DslComponent {
    fun visitInput(visitor: InputTraversal) = visitor.node(instance, instance.children)
}

interface InputTraversal {
    fun node(component: DslComponent, children: List<DslComponent>)
    fun withTransform(transform: Transform, block: () -> Unit)
    fun withClip(rect: Rect, block: () -> Unit)
}

InputTraversal 由核心创建,公开操作全部返回 Unit;组件不选择路由模式,不传回 owner 或包装路径。node 在当前几何作用域中报告一个逻辑节点及其输入子节点,核心安排回调与短路;两个 with 操作只维护作用域。

以下为 DslRoot 的平台入口,均无默认参数,取代经 root.component 向下广播输入:

fun dispatchPointer(event: PointerEvent): Boolean
fun dispatchKeyDown(key: Key, scanCode: Int, modifiers: KeyModifiers): Boolean
fun dispatchKeyUp(key: Key, scanCode: Int, modifiers: KeyModifiers): Boolean
fun dispatchCharTyped(c: Char): Boolean
fun dispatchPreedit(info: PreeditInfo)
fun dispatchScrollVertical(position: Position, amount: Double): Double
fun dispatchScrollHorizontal(position: Position, amount: Double): Double
fun dispatchDropFiles(position: Position, files: Array<Path>): Boolean

滚轮暂保留现有分轴名称和余量契约,不纳入 PointerEvent。平台入口位置为根坐标,组件滚轮/拖放回调位置为局部坐标。render 移除单一 mouse Position 上下文。DslRootInput 删除 mouse/isMouseDown,保留 isKeyDown/setPreeditArea;系统窗口/表面捕获由适配器管理,不等同于核心捕获。

所有自身输入回调禁止递归 children。DslScope、Lazy 和旧全局通知中的递归必须一起移除,不能只改返回类型。一个 DslChild 装饰链仍是同一 identity:行为包装可调用捕获的 inner 自身回调,不能调用 instance 重新进入外层。非 Up/Cancel/Leave 事件由 inner 优先,第一个非 IGNORED 结果胜出;Up/Cancel 经过链上全部行为,按本事件对应动作清理,非最终 Up 不结束其它按键,业务激活仍按 inner 消费结果短路。Leave 同样透传全部行为,但只清指向/表面效果,绝不能清按压、拖拽或候选数据。同一逻辑节点只有一份路由结果,要独立 owner 就创建真正子节点。

上述包装保证 inner 抛错后本层仍在 finally 执行本事件相应的清理,再与本层失败聚合重抛;Leave 的清理范围仍仅限指向/表面效果。inner 已失败时不执行本层激活/音效;只有 inner 成功且未消费时才允许本层业务激活,清理不能依赖激活成功。内置行为统一遵守这一约定,才能保证 Root 将最终 Up 视为已终止后不补 Cancel 时,外层也不会遗留活动状态。

globalFocusChanged/globalHoverChanged 仍为每个已物化逻辑节点一次的状态广播,装饰器可委托 inner;preedit 改为定向自身回调,移出全局接口。指针焦点来源为 FocusSource.POINTER。

遍历与几何算法

每次路由按需使用临时路径栈,栈项含当前组件、DslId、局部到根变换及带各自坐标系的 clip。查询结束释放;不默认复制整树,不建立第二张持久输入树或注册中心。跨事件只缓存当前树版本的 DslId → 子索引路径,不缓存组件或几何;构建前、提交、rollback 及挂载变化即清空。每次定向输入沿提示解析当前组件及完整几何,提示不再对应目标时重新短路寻址。一次输入仅缓存实际访问的分支供命中、回调内相对变换和定向解析复用,边界结束即释放。

  1. Root 虚拟入口仅顺序访问挂载 Screen,不进入 node、不读取虚拟 identity;Screen 是真实有身份节点。
  2. node 先将当前节点与已累积几何压栈,再按声明顺序访问孩子,最后按路由策略处理自身,退出弹栈。父 rect 不命中只跳过父自身,不能裁子树;只有显式 clip 裁子树。
  3. 每个孩子从最外包装开始 visitInput。几何包装执行 visitor.withTransform(本层增量) { inner.visitInput(visitor) } 或 visitor.withClip(instance.rect) { inner.visitInput(visitor) };普通行为包装直接委托 inner.visitInput。底层只报告一次 node(instance, instance.children)。
  4. 当前局部到根为 M、本层绘制变换为 T 时,块内为 M×T;clip 保存进入时的 M。作用域以 finally 恢复。不能再乘一次聚合 component.transform,不能通过 instance 再入外层造成双重变换。
  5. Lazy 在自身 node 传 visibleChildren;声明 children 继续用于布局与导航。查询、定向寻址、广播不构建离屏项。Overlay 按实际挂载绘制路径遍历,不继承已脱离的原声明处 clip。
  6. 根点分别映射到各 clip 的局部空间判断,不能把旋转/透视区域降为最终 AABB。新命中剪掉 clip 外分支;定向寻址不以 clip 阻断,仍保存它供待定最终 Up 判定。
  7. 新 Down 按子优先、上层兄弟优先调用自身。整个子分支 IGNORED 才尝试后面的兄弟;首次 TRACK 保存当前栈路径并停止所有旁支,只回溯该路径祖先。祖先自身 rect 与完整 clip 命中才收到 Down:TRACK 追加候选,HANDLED/CAPTURE 停止回溯。没有候选时,HANDLED/CAPTURE 直接结束搜索。
  8. 定向路由按 ID 解析当前物化路径后投递,沿途普通祖先处理器不调用。待定候选按保存顺序逐个投递,各用当前几何。纯查询/广播不调用 onPointer;visitor 内部停止状态阻止之后的 node/作用域展开旁支。

路径只拷贝本次必要栈项,不作为新公开返回载荷。一次事件期间不换树版、不半路重算几何;回调引起的结构变化在安全点处理。

同节点全部行为使用完整装饰链后的局部位置,受全部输入 clip 约束,clickable 放在几何装饰器另一侧不能绕过约束。几何包装从事件方法删除重复转换,这是明确的装饰器行为调整。renderScissor 仍只裁绘制,scissor 同时裁输入。

现有 testHit 两种查询封装同一遍历,不再各自递归。带位置查询受完整 clip 约束;无位置查询只看物化节点,不按 clip 点过滤。声明导航单独保留,不能用无位置 testHit 代替它。

目标、穿透和指向

IGNORED 只表示本次未处理,不能证明没有输入能力;Root 不试发 Down 探测,也不把 rect 命中等同于消费。

工作 目标与传播 clip
新 Down 依遍历顺序;TRACK 选分支,HANDLED/CAPTURE 停止 完整准入
无候选/独占的 Move 同样的命中顺序;HANDLED 停本次,不建立跟踪 完整准入
待定 Move、追加 Down、非最终 Up 原候选由内向外;HANDLED 停本次 不阻断
独占 Move/Down/Up 仅独占 ID,经当前路径转换 不阻断
待定最终 Up 由内向外,首个 HANDLED 接受结束 各候选重查自身 rect 与完整 clip
Cancel 原参与者由内向外,各一次 无位置,不阻断
滚轮/文件拖放 首个有消费者的命中路径,目标到祖先 新命中完整准入
按键 物化焦点节点到其 Screen 祖先,未消费再 Root 导航 无点过滤
字符/IME 单一文本目标;组合结束仍定向原目标 无点过滤
全局状态通知 物化树每逻辑节点一次 无点过滤

声明靠前仍绘制在上、输入优先。滚轮以余量是否改变判消费,完全未消费的分支可继续找背景;一旦消费,余量只交该路径祖先,不交背景兄弟。拖放以 Boolean 判消费。

指向是无副作用的几何查询:首个 highlightable || tooltip != null || narratable 节点成为 anchor,tooltip/narration 仅沿它的当前祖先链由内向外派生,不回头找背景。这是显式元数据策略,不检测 onPointer 是否覆写;自定义指针控件要指向效果就设置现有 highlightable。highlightable=true 只允许高亮,不要求绘制高亮,也不隐式可聚焦。

纯装饰穿透;模态遮罩 DSL 应统一安装输入处理与 highlightable=true,既阻挡新输入又阻挡背景提示,避免调用方漏配。模态出现不会抢走既有独占,需中断时关闭/隐藏原交互表面。这相对按目的独立命中的旧提案有意改变:不能再从不同背景分别取高亮、tooltip、朗读。

disabled 内置控件保留行为包装:新输入 IGNORED、focusable/highlightable 随 enabled 关闭;旧序列继续收尾并停止业务更新。保留 tooltip 属于有意保留指向。需要禁用区阻挡背景时由包装显式 HANDLED 并提供指向元数据,不增加通用 enabled/opaque 字段。

每个 id 独立指向,TOUCH 接触期间也有;canHover=false 最终 Up 清除,true 可继续悬停。Leave 清指向、不终止候选/独占;向活动参与者各发送一次 Leave,无活动者时只发上次指向 anchor,忽略结果。globalHoverChanged 广播对应 id 的新目标;重复 Leave 无变化不再通知。Leave 后旧位置不参与布局重算,下一次真实位置输入才恢复,失去来源必须 Cancel。

isHovered 表示至少一个指针指向本节点;独占拖出后可不 hovered。Tooltip 只选 canHover 指针,触摸默认显示按压反馈;多来源取最近真实位置事件,平局按稳定 id;先确定几何 anchor 再找其祖先提示,不因该分支没有 tooltip 而改找较旧指针或背景焦点。完全没有合格悬停 anchor 时使用焦点提示,仅由目标所属 Screen 构建。树/布局变化重算静止指向,不伪造 Move;原地压力 Move 是真实事件,照常投递,但零位移不越过移动阈值、不触发拖滚。

状态与结果

Root 每身份保存最新根样本、按钮/设备信息、位置是否仍参与指向,以及以下互斥路由状态;指向目标独立保存。控件只存自身业务数据与活动 id。

状态 内容与后续
无跟踪 无目标;新按钮 Down 可重新命中,Move 可空间分发,Up 不找新目标
待定 有序候选 ID,首项即 anchor,不重复存 anchor 字段;沿原候选等待认领或最终 Up
独占 一个 DslId;全部按钮变化与 Move 只到它,不另存 press/旧对象/分按钮表
排空 无参与者、buttons 尚非空;吞残余序列,buttons 清空或原生 Cancel 后结束
回调阶段 IGNORED HANDLED TRACK CAPTURE
无跟踪的新 Down 继续搜索 本次消费,无订阅 登记并回溯原路径 独占当前 ID
待定追加 Down 留候选、继续 留候选、停本次 留候选、继续,不增新节点 当前候选胜出
待定 Move 留候选、继续 留候选、停本次 非法 当前候选胜出
待定非最终 Up 留候选、继续 留候选、停本次 非法 非法
待定最终 Up 本候选结束、继续 胜出,取消未结束候选 非法 非法
独占 Down/Move 保留独占、仍消费 同左 非法 仅继续当前独占
独占非最终 Up 保留独占、仍消费 同左 非法 非法
独占最终 Up 结束独占 结束独占 非法 非法
无跟踪 Move 继续命中 停止本次 非法 非法
Cancel/Leave 忽略结果 忽略结果 忽略结果 忽略结果

TRACK 只在 Down 请求等待;已登记者后续无需重复 TRACK。CAPTURE 仅在接受 Down 或待定 Move 时建立,已独占者在 Down/Move 再 CAPTURE 只确认保持;任何 Up 均不得返回 CAPTURE。非法结果视为组件协议错误,终止本指针交互并报错,不悄悄降级。外部节点不能转移既有独占。

首次 Down 回溯时祖先 HANDLED 取消已登记子候选,结束等待;祖先 CAPTURE 或待定认领先确定独占,再由内向外 Cancel 输家。胜者已收到触发事件,不重放 Move、不合成第二个 Down。取消一处抛错不阻止其余清理。

待定最终 Up 在任何回调前摘除整组订阅。当前几何不命中的候选收到 Cancel,其余逐个 Up;首个 HANDLED 后,其它未收到终止事件的都 Cancel。已收到 Up/Cancel 的不能再次取消或激活;没有 HANDLED 则全部自然结束。独占最终 Up 也先摘归属,再投最终位置。Cancel 只清理,不激活、不发确认音效。

dispatchPointer 返回本次是否消费:HANDLED/TRACK/CAPTURE、既有候选/独占和排空序列均 true,即使自身返回 IGNORED;无跟踪且全忽略为 false。单次 HANDLED 不承诺后续订阅。无跟踪 Up 不命中其他控件,未见 Down 的控件不能因此激活。

同鼠标 PRIMARY Down、SECONDARY Down、Move、PRIMARY Up、SECONDARY Up 的 buttons 依次为 {PRIMARY}、{PRIMARY,SECONDARY}、相同、{SECONDARY}、{}。候选/独占期间追加按钮不重新命中、不增候选,每次 Move 每参与者最多一次;非最终 Up 只结束该按钮业务,Root 到最后 Up 才释放序列。主动作提前结束仍须清理剩余按钮。

单指控件占用时对其它 id 的 Down 返回 HANDLED,防止穿透;第二指不能改变或结束第一指。候选只来自原 Down 分支,划过其它控件不使其获得认领资格。

手势、坐标与焦点

内置交互 策略
鼠标/PEN clickable PRIMARY Down 激活并 HANDLED,保留现有按下触发习惯
TOUCH clickable Down TRACK;Move 与最终 Up 均检查根坐标容差;超容差只标不可点击并 IGNORED,继续让父观察;有效最终 Up 激活并 HANDLED
Slider/滑块/调色板/选区 接受活动 id 后 CAPTURE,Move 更新,Up 应用最终位置并清理,Cancel 只收尾
TOUCH 滚动 Down TRACK;越过按尺度换算的轴向阈值且该方向能滚动时 CAPTURE
嵌套 TOUCH 滚动 同时成立内层先;内层初始方向已到边界则外层认领;认领后到边界仍归内层直到结束
多点画布 同节点分别捕获多个 id,保存各根样本;触点增减重设中心/距离/角度基准

待定期间不做不可撤销动作。首批触摸认领后无跨层接续/余量协作,滚轮仍传余量;当前 PointerResult 不能暗中承诺触摸余量协作。父容器不能从两个已独占子控件原子抢夺,组手势另议。PEN 默认不参加触屏拖滚,命中控件处理,画布可同时接纳笔压与其它触点。

保持事件局部 position,不增加 rootPosition/新公开投递上下文;修正既有查询:

fun DslComponent.relativeTransform(parent: DslComponent): Transform?

查询复用 InputTraversal 的完整同节点装饰器顺序;投递时优先复用当前路径,不为每个回调重扫树。对 Root 虚拟节点用引用判断并隐式单位变换,不读 identity。未物化、非祖先、不可逆或非有限映射返回 null,不能从旧 transform 聚合属性另拼输入坐标。

相对拖动保存上次根坐标;当前事件经 local→root 得新根样本,前后根样本都经本次 root→local 后求差,不能相减两个布局版本的局部位置。点击容差比较根样本与按 Root 逻辑尺度换算的距离,布局移动本身不越阈值。画布优先变换子内容,让手势表面稳定。新目标遇无效映射忽略该分支,已有交互取消;输入逆变换必须可识别失败,不能使用当前 Transform.invert 的奇异矩阵单位回退,透视除零/非有限结果也不得送给控件。

键盘焦点和朗读各一份。鼠标/PEN 接受 PRIMARY Down 后沿接受路径取最近 focusable;TOUCH 在有效点击确认或可聚焦控件接受 Down 并 CAPTURE 后取焦点;TRACK Down 不取焦点,父滚动不替子按钮取焦点。Move 不抢焦点;设置前复核存活,回调直接改变焦点时尊重其决定。

无焦点不向组件投按键,只在最上层挂载 Screen 的导航视图运行 Root 内置导航;有焦点沿当前物化路径到所属 Screen,未处理仅在该 Screen 运行一次 Root 导航,不再扫描其它 Screen/全树。keyUp 未处理直接返回 false,不触发导航。返回 false 后由拥有 Root 的应用处理跨 Screen 导航和全局快捷键;原先无焦点任意子节点接键的行为移除,这是 alpha 行为调整,首批不新增快捷键注册或键盘捕获 API。

模态层要隔绝原焦点键盘输入,打开时必须迁移/清除焦点;视觉在上不会使旧焦点路径自动失效。模态作为最上层 Screen 时,清焦点后 Tab 只搜索该 Screen,不落背景;Overlay 不自动成为原控件的键盘路由祖先,全局快捷键交 Root 调用方处理,不在这里增加模态/焦点栈系统。

字符只给物化文本焦点。首个非空 preedit 记录组合目标 ID,后续及空 preedit 都定向它;切焦点/目标消失先向旧目标送空 preedit 并清组合记录,再启用新目标。迟到旧组合输入由适配器按平台组合顺序过滤,不能发给新焦点。

导航与输入树分开:viewHorizontal/viewVertical/viewSequential 可含未物化声明项,选择焦点不构建离屏内容。变化先广播物化容器,Lazy 按声明身份滚动,下一正常布局物化目标。焦点对账依据声明/导航可达性,不能因输入树缺失提前清除;等待物化时不向该目标投键盘/文本,Root 仍在其所属 Screen 导航。声明/容器确实移除、隐藏、关闭,或目标不再 focusable 时清焦点。未声明的深层离屏内容不凭空发现,先到声明项并物化再继续。指针捕获始终只认可物化输入树,不使用此导航例外。

树交接与终止

输入、建树、布局、提交、回调、清理在会话线程串行,输入不穿插临时构建树。所有平台输入入口共用同一路由重入边界,覆盖指针、键盘、文字/IME、滚轮和拖放;同步重入任一入口均在修改状态前报错,平台事件排队到当前路由后。setFocus 和内部清理通知属于状态操作,按既定规则执行,不当作新的平台输入入口。回调请求隐藏/挂载/关闭时先记录延后变更,返回后停止普通投递,在安全点交接/取消,不在回调栈里销毁其 local。关闭领取后即终态,不再接受新事件或 CAPTURE。

成功换树由 DslScreen/DslDataStore 按以下边界提交:

  1. 暂留旧 children/overlays;完整构建、布局候选及 overlay/tooltip,验证遍历结构与物化 ID 唯一。无效几何标为不可路由而不是单位矩阵。构建失败恢复旧树/归属,沿用失败帧不扫 local,不承诺回滚业务副作用。
  2. 新树解析所有活动 ID。独占同 ID 存在则沿新路径继续;待定只保留原首项当前祖先路径上的原候选,不补新祖先,按当前由内向外排序。首项消失/虚拟驱逐则整组取消;失效变换也取消相关交互。
  3. 构建前只为活动指针、指向、焦点及 IME 目标保存短期旧路径;先摘需取消归属,暂存本次旧节点引用;发布新树及保留归属,再向退出者的旧树发 Cancel,此时旧 local 可读,回调看到已提交新树,不能重新捕获旧对象。
  4. 对账焦点/IME/指向,所有清理排空并聚合异常。取消/通知回调主动切焦点时,已移除的组合目标仍可经本边界旧路径收到空 preedit。此阶段在构建 rollback 的 catch 之外,Cancel/通知异常不能回滚新树或恢复已终止交互。
  5. 释放旧树临时引用,渲染新树;成功帧末才扫 local。清理/渲染失败沿用跳过扫描语义,但保留已提交新树和已收敛归属,下一成功帧或关闭清除残留。

同 DslId 就是同逻辑节点,每帧换对象不取消。核心不从实现变化猜测终止:disabled 保留包装和清理;任意同 ID 重组行为也必须保留旧活动状态与终止处理,做不到就换 identity 让旧树 Cancel,不能照搬 clickable(enabled=false) 直接不装饰的旧写法。

隐藏/卸载、Screen/Root 关闭同样暂留旧树,再摘归属、Cancel、清指向/焦点/IME,最后销毁属性与树。逻辑目标消失只终止逻辑交互,物理 buttons 非空则排空到最后 Up,不能伪造释放或把残余事件交背景。原生 Cancel 清该身份全部状态,未知/重复 Cancel 幂等;悬停由后续真实位置恢复。Root 关闭复用内部取消流程,不重入关闭的公开入口。

Root 关闭在回调前只保存必要旧目标及祖先路径,包含已标记 closed、实际销毁仍排队的 Screen。整个关闭边界复用该旧目标上下文;取消回调内再关闭 Screen,或 Screen/Root 关闭请求已按任一顺序排队,都不能让当前树过滤 closed Screen 后漏发空 preedit。取消、组合结束、焦点清理与各属性释放仍排空并聚合异常,空 preedit 必须先于原目标 local 销毁。

普通回调异常先摘本指针剩余归属,再逐个 Cancel,已收到最终 Up/Cancel 者不重复;需要时转排空并聚合报错。一参与者异常不阻断其它 id 的关闭清理。回调中请求隐藏/关闭后,返回的捕获请求作废。

重复 Down、矛盾 buttons、非有限位置、非法 pressure 为协议错误,先收敛已有交互再报错,不合成可激活的 Up;有效按钮快照用于排空,否则等适配器 Cancel 重同步。未知 Up 不投递,重复最终 Up 不二次激活。适配器不能任意合并 Down/Up/Cancel,也不能丢原地压力 Move。

跨线程 close 保留一次性终态领取,但取消/销毁调度到会话线程,跨线程调用等待清理后返回,等待不持生命周期锁。调度不能依赖即将取消的 sessionScope,后端必须在清理后才停 dispatcher/frame 驱动。回调内 close 在当前事件/构建安全点完成延后清理,不自等;调用者也不能持有会话线程正在等待的外部锁来同步 close。本任务不扩展为属性/协程体系重写。

实施与验收

实现已拆除 DslScope 输入递归,DslChild 共享 instance 只报告单节点,Lazy 分离声明与物化视图;Root 按指针保存 ID,Screen 暂留旧树并在 frame 扫描 local 前取消,输入使用可识别失败的逆映射。ScrollBar thumb 同时处理捕获和 Move 业务,不依赖捕获后祖先广播。MouseTip、Tooltip、hoverMask、调色板使用事件或 Root 内部指向状态;首批不公开全量可变指针快照。

核心实现分为下表四层;后端分别适配统一入口。PointerCanvas 提供基础多点变换,modalBarrier 同时设置指向元数据与输入阻挡。构建与测试结果以及实际来源范围由各仓验收记录说明。

步骤 交付与完成条件
1. 结构/几何 visitInput、增量装饰器、Lazy 输入视图、查询/relativeTransform 统一、拆回调递归;路径/精确 clip/虚拟 Root/无双变换测试
2. 协议/路由 类型、Root 入口、四状态、合法性、候选、多按钮、重入异常;假后端覆盖全部转移
3. 提交/清理 旧树暂留、提交/rollback 分界、ID 对账、local 前取消、延后变更、会话线程关闭;生命周期回归
4. 控件/状态 点击/滑块/选区/拖滚/画布、ScrollBar owner、hover/焦点/IME/导航、渲染去单 mouse;统一终止包装的异常排空,新增多点示例及交互测试
5. 后端适配 Web Pointer Events、Swing AWT、当前 MC Fabric 1.20.1 GLFW 均使用统一入口;各仓编译及模拟输入测试通过,真实触点/笔压/原生捕获须另做设备验收
验收面 必须观察的场景
多指/设备 两指各拖 Slider、单控件拒第二指、画布增减触点、鼠标/触摸/PEN 并存,同鼠标多键始终单 owner
压力 PEN 悬停/笔尖/侧键身份连续,0/1/非法值、无压感默认、侧键 Up 保压、原地 Move、最终 Up 归零、变换不改压力
几何 装饰器换序,嵌套旋转/缩放/剪切/透视及 clip;外部 Down 不达、候选出界可观察、裁剪外 Up 取消点击、独占收最终位置、失效映射取消
竞争 子点击/父滚动、嵌套同轴/异轴阈值与初始边界、认领后不接续;划过不能认领,输家一次 Cancel,多按钮部分释放保序列
命中/指向 忽略覆盖层穿透、模态挡输入与提示、disabled 新输入及旧清理,多指 hover 聚合、静止布局不伪造 Move/压力
生命周期 同 ID 换对象/行为连续性、换 ID、候选重挂/首项消失、Lazy 驱逐;旧 Cancel 在 local 前,构建失败保旧树、清理/渲染失败保新树
终止/异常 最终 Up/Cancel 先摘归属,非最终 Up 保留其它按键,Leave 只清指向/表面效果且交互继续;失焦/丢原生捕获,重复/乱序、非法结果、回调抛错/重入/关闭;同节点 inner 抛错外层仍按本事件清理,最终终止不重复投递/激活
焦点/IME/导航 触摸确认才取焦点、滚动不抢焦点,IME 结束定向旧目标;Lazy 导航先声明后物化,不清待物化焦点、不保离屏捕获;无焦点/未消费按键不全树重复投递
性能 鼠标/多点 CPU 与分配量,定向路径按树版失效,无活动不扫捕获,不每触点每帧复制全量索引

空间查询最坏 O(N),N 为物化节点数;P 个指针完整重查最坏 O(PN)。活动 ID 可按树版批量解析路径,不宣称统一路由自动成为 O(P)。

Web 参考 W3C Pointer Events:多按钮不能机械映射 pointerdown/up,须由 buttons 正规化追加 Down/Up,过滤兼容 mouse/click,处理浏览器接管与原生丢捕获。MC/桌面真实多点来源由对应后端核验,鼠标模拟不算原生多点通过。

核心的自动化回归覆盖多指、压力、几何裁剪、竞争、换树和异常终止,TestMultiPointerPage 提供独立双滑块与画布示例。访问计数回归确认 128 个旁支下,缓存焦点的字符/按键输入及稳定指向的已捕获 Move 仅解析所需路径,首次接受后及显式 clip 外查询不展开旁支。空间搜索无可提前返回目标、指向变化后的全局广播、候选身份验证仍可能访问全部物化节点;按需缓存最坏也可达到 O(N)。尚未做真实设备或 CPU/分配量基准,访问次数不等价于耗时或字节分配收益;上表性能项保留为测量要求。

首批包含 PEN 压感、触摸点击/拖滚、基础多点画布;不包含惯性、长按、倾角、系统软键盘、触摸认领后跨层接续和跨独占者组手势。真实设备的触点、笔压与原生表面捕获须按后端单独验收。

核查方式:codebase MCP 定位结构并检查依赖文件覆盖;索引报告 Kotlin context 解析缺口与元数据变化,相关结论已直接读取源码补齐,不把缺失调用边当作不存在调用。


This site uses Just the Docs, a documentation theme for Jekyll.