事件

Root 统一路由输入,组件回调只处理自身,不递归 children。声明靠前的子节点绘制在上方,输入也优先。同一父节点先依声明顺序尝试全部子分支,再处理父自身;首次 TRACK 后只回溯原路径祖先。

指针

鼠标、触摸与笔统一调用 onPointer(event: PointerEvent): PointerResult。默认返回 IGNORED,它是普通成员函数。事件包含稳定的 PointerId;位置为当前节点局部坐标,仍可直接与 instance.rect 比较。

  • Down / Up 带变化的 button 及变化后的完整 buttons 集合。
  • Move 带完整按钮集合;原地压力改变也会投递。
  • pressure 在 0f..1f,无压感按住时默认 0.5f,无按钮时为 0f。生命周期由按钮表达,不由压力推断。
  • Cancel 结束这个身份的全部交互,只清理,不激活、不更新值、不播放确认音效。
  • Leave 清表面指向,拖拽仍继续;来源丢失必须由后端提交 Cancel。
结果 含义
IGNORED 本次未消费,新输入可继续找后面的节点
HANDLED 消费本次,不订阅后续
TRACK 只可在 Down 返回,参与当前命中分支的待定序列
CAPTURE 在 Down 或待定 Move 认领该指针

独占按 PointerId → DslId 保存。同鼠标所有按钮共用一个独占者;不同触点可以独立拖动两个控件。认领后只有独占者收到事件,最终 Up 带最后位置并先释放归属,再执行回调。任何 Up 都不能返回 CAPTURE。未知/重复终止不会激活新目标;非法结果或错误按钮快照会清理交互并报错。

TRACK 适合触摸点击与父滚动竞争:等待期间不做不可撤销动作,父容器越过阈值后可认领,其他候选收到一次 Cancel。待定最终 Up 会重查矩形与完整裁剪;出界候选收到 Cancel。独占拖拽可在裁剪外继续并收到最终位置。

内置 clickable 对鼠标/PEN 主键仍在按下时激活,对 TOUCH 等到有效最终 Up;Move 与最终 Up 均检查根坐标中的 8 × root.scale 容差,布局移动本身不计入位移。禁用包装仍存在以结束旧序列。Slider、调色板、滚动条与选区单次接纳一个指针,第二指会被消费但不会改变第一指。

自定义拖拽

活动状态保存在 local / stable 中,绑定稳定组件身份。接受主键时保存 event.id 并返回 CAPTURE;匹配的 Move 更新业务;主键 Up 应用最终位置;Cancel 只清理。把终止清理放在 finally,内层或业务回调抛错时仍必须清理自身。

同一身份的每帧新对象代表同一逻辑控件。行为不能保留原序列时,换 identity 让旧节点取消。Root 在成功换树后、旧 local 清扫前发送取消;构建失败保留旧树。组件不调用额外捕获或取消方法。

PointerCanvas 可直接提供基础平移、缩放和旋转:

PointerCanvas(modifier, id = "canvas", onGesture = { translation, ratio, radians ->
    offset += translation
    zoom *= ratio
    angle += radians
}) {
    content().rotate(angle).scale(zoom).move(offset)
}

手势表面应保持稳定,只变换内容。增加或移除触点只重设基准,不产生跳变;跨独占子控件的组手势不在此接口内。

几何与渲染

visitInput(visitor) 报告物化节点;withTransform / withClip 按装饰器顺序增量贡献几何。一个装饰链只报告一个逻辑节点。自定义虚拟容器报告实际物化子节点,声明导航列表单独保留。输入回调中不要再次逆变换位置。

testHit 与 relativeTransform(parent) 复用此遍历。不可逆或非有限映射无法路由;带位置查询受完整裁剪约束。

render 只需要 context(renderer, renderParam)。自定义容器反向绘制子节点,输入不再由绘制或单鼠标位置上下文驱动。

键盘、IME、滚轮与拖放

键盘从物化焦点节点沿路径到所属 Screen;未消费再由 Root 在同一 Screen 导航。无焦点只在最上层 Screen 导航,不向全树广播;Root 返回 false 后由应用处理全局快捷键。

charTyped 只到文本焦点。preedit 定向组合开始时的文本目标,组合结束、焦点变化或目标移除时先向旧目标发送空组合。

滚轮回调返回余量。完全未消费的分支可穿透背景,一旦消费,余量只交该路径祖先。拖放沿命中路径以 Boolean 判消费。

焦点与指向

root.setFocus(identity) 是代码设焦点入口,null 清除;来源为 KEYBOARD、POINTER 或 CODE。TOUCH 待定点击确认后获焦点,可聚焦控件在 Down 立即捕获时也可获焦点;Move 认领滚动不抢焦点,回调主动设置的焦点会保留。失去声明或不再可聚焦的目标会在提交时清除;Lazy 声明焦点可先导航、再于正常布局物化。

模态表面可使用 modalBarrier() 同时阻挡新指针、滚轮、拖放和背景提示;已有独占不被新模态抢走。打开模态时由应用迁移或清除键盘焦点。

每指针分别指向几何上最前的 highlightable || tooltip != null || narratable 节点。isHovered 表示至少一个指针指向本节点;tooltip 和朗读只沿该节点的祖先链派生。提示只选能悬停的指针,先选最近的几何锚点再沿祖先找提示;该分支没有提示时不回退到背景或较旧指针。完全没有悬停锚点时可使用键盘焦点提示,仅由所属 Screen 构建。触摸默认使用按压反馈。

globalFocusChanged 和 globalHoverChanged(pointerId, newHover) 由 Root 每个物化逻辑节点广播一次,组件不递归子树。所有平台入口共享重入边界;hover 等回调请求隐藏、挂载或关闭后会停止本轮普通输入投递,并在安全点清理,不能同步重入平台输入。


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