多点输入
核心契约:统一指针输入、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 |
| 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 及挂载变化即清空。每次定向输入沿提示解析当前组件及完整几何,提示不再对应目标时重新短路寻址。一次输入仅缓存实际访问的分支供命中、回调内相对变换和定向解析复用,边界结束即释放。
- Root 虚拟入口仅顺序访问挂载 Screen,不进入 node、不读取虚拟 identity;Screen 是真实有身份节点。
- node 先将当前节点与已累积几何压栈,再按声明顺序访问孩子,最后按路由策略处理自身,退出弹栈。父 rect 不命中只跳过父自身,不能裁子树;只有显式 clip 裁子树。
- 每个孩子从最外包装开始 visitInput。几何包装执行
visitor.withTransform(本层增量) { inner.visitInput(visitor) }或visitor.withClip(instance.rect) { inner.visitInput(visitor) };普通行为包装直接委托 inner.visitInput。底层只报告一次 node(instance, instance.children)。 - 当前局部到根为 M、本层绘制变换为 T 时,块内为 M×T;clip 保存进入时的 M。作用域以 finally 恢复。不能再乘一次聚合 component.transform,不能通过 instance 再入外层造成双重变换。
- Lazy 在自身 node 传 visibleChildren;声明 children 继续用于布局与导航。查询、定向寻址、广播不构建离屏项。Overlay 按实际挂载绘制路径遍历,不继承已脱离的原声明处 clip。
- 根点分别映射到各 clip 的局部空间判断,不能把旋转/透视区域降为最终 AABB。新命中剪掉 clip 外分支;定向寻址不以 clip 阻断,仍保存它供待定最终 Up 判定。
- 新 Down 按子优先、上层兄弟优先调用自身。整个子分支 IGNORED 才尝试后面的兄弟;首次 TRACK 保存当前栈路径并停止所有旁支,只回溯该路径祖先。祖先自身 rect 与完整 clip 命中才收到 Down:TRACK 追加候选,HANDLED/CAPTURE 停止回溯。没有候选时,HANDLED/CAPTURE 直接结束搜索。
- 定向路由按 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 按以下边界提交:
- 暂留旧 children/overlays;完整构建、布局候选及 overlay/tooltip,验证遍历结构与物化 ID 唯一。无效几何标为不可路由而不是单位矩阵。构建失败恢复旧树/归属,沿用失败帧不扫 local,不承诺回滚业务副作用。
- 新树解析所有活动 ID。独占同 ID 存在则沿新路径继续;待定只保留原首项当前祖先路径上的原候选,不补新祖先,按当前由内向外排序。首项消失/虚拟驱逐则整组取消;失效变换也取消相关交互。
- 构建前只为活动指针、指向、焦点及 IME 目标保存短期旧路径;先摘需取消归属,暂存本次旧节点引用;发布新树及保留归属,再向退出者的旧树发 Cancel,此时旧 local 可读,回调看到已提交新树,不能重新捕获旧对象。
- 对账焦点/IME/指向,所有清理排空并聚合异常。取消/通知回调主动切焦点时,已移除的组合目标仍可经本边界旧路径收到空 preedit。此阶段在构建 rollback 的 catch 之外,Cancel/通知异常不能回滚新树或恢复已终止交互。
- 释放旧树临时引用,渲染新树;成功帧末才扫 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 解析缺口与元数据变化,相关结论已直接读取源码补齐,不把缺失调用边当作不存在调用。