Zayden-Jung/endorphin-tessera-gui
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: explain native input capture and window event lifecycle

Browse Source
This commit is contained in:
Codex Bot
2026-11-12 19:25:56 +08:00
parent b95912d840
commit 0971d08e1b
1 changed files with 97 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/shell/app.rs
+97 -1
View File
@@ -582,10 +582,12 @@ impl TesseraApp {
}
/// 判断指针是否被侧栏或管理面板覆盖，阻止一次点击同时落入页面。
// guest_point 与页面手势/焦点分流共用，普通页面命中先排除宿主逻辑占用区域，而非只排除实际按钮。
fn guest_covered(&self, point: Point) -> bool {
if self.sidebar.covers(point) {
return true;
}
// 开发工具命中区域额外向外扩 6 单位，涵盖分隔线附近，避免边缘拖动同时穿透页面。
let panel = self.layout.developer_tools.panel;
self.developer_tools.open
&& crate::geometry::Rect::new(
@@ -598,12 +600,15 @@ impl TesseraApp {
}
/// 排除宿主管理区域后，把原生指针转换到页面使用的坐标系。
// 普通命中、指针派发和手势入口共用；返回页面 Surface 世界坐标，局部视口/面板逆变换仍由后续几何处理。
fn guest_point(&self) -> Option<Point> {
if self.guest_covered(self.pointer) {
return None;
}
let current = self.namespace.read().ok()?;
// 先扣侧栏逻辑宽度得到页面视图点，不能在 Surface::to_world 后再扣，否则侧栏偏移会被相机缩放。
let point = Point::new(self.pointer.x - self.sidebar.left(), self.pointer.y);
// 在页面视图空间先检查可见分配边界；未发布 viewport 时仅排除负坐标，不擅自推断窗口尺寸。
if point.x < 0.0
|| point.y < 0.0
|| current
@@ -616,6 +621,7 @@ impl TesseraApp {
}
/// 从页面坐标与当前帧命中结果构造带版本的点击输入。
// 鼠标按下/释放、指针订阅入口和光标显示共同读取当前帧的粗命中，不在 GUI 内调用源 hitTest。
fn guest_hit(&self) -> Option<crate::events::Input> {
let point = self.guest_point()?;
let current = self.namespace.read().ok()?;
@@ -624,6 +630,7 @@ impl TesseraApp {
return None;
}
// 命中的是当前发布帧，事件同时携带 session/layout_version；worker 可拒绝排队期间已过期的输入。
// Frame 先通过空间候选与原生 contains 选择交互出现，真正源命中及按下/释放比较留给 worker。
let mount = frame.hit_test(point)?;
Some(crate::events::Input {
window: self.resource,
@@ -641,26 +648,32 @@ impl TesseraApp {
/// Pointer subscriptions explicitly opt a Mount into continuous input.
/// Capture retains window/session/Mount; the worker validates it again.
/// 左键捕获和悬停移动共用，从粗命中出现向祖先寻找 pointer 订阅，不把所有交互目标都当作连续指针接收者。
fn pointer_target(&self) -> Option<crate::events::Input> {
let mut input = self.guest_hit()?;
let current = self.namespace.read().ok()?;
let frame = &current.document.frame;
let mut mount = frame.mounts.iter().find(|m| m.id == input.mount)?;
// 当前出现没有订阅就沿父链找最近订阅祖先；无父或父项缺失时 None，不穿到其他兄弟。
while !mount.pointer_events {
mount = frame.mounts.iter().find(|m| Some(m.id) == mount.parent)?;
}
// 将事件目标改为订阅出现，清 press_point 以区别普通按下/释放合成 click；会话版本仍来自命中令牌。
input.mount = mount.id;
input.press_point = None;
Some(input)
}
/// move_pointer、cancel_pointer 及左键 down/up 调用，沿用捕获的窗口/会话/出现身份，仅替换类型和可用位置。
fn emit_pointer(&self, mut input: crate::events::Input, kind: &str) {
input.kind = kind.into();
input.press_point = None;
// 能取得当前页面点就更新，否则保留令牌旧 point；离开宿主可转换区域时也能发送取消/释放到原目标。
if let Some(p) = self.guest_point() {
input.point = Some([p.x, p.y]);
}
self.event_client.send(input);
}
/// CursorLeft 和失焦时调用，take 消费捕获与悬停，分别发 cancel/leave，避免下一次清理重复发送。
fn cancel_pointer(&mut self) {
if let Some(input) = self.pointer_capture.take() {
self.emit_pointer(input, "pointercancel");
@@ -669,11 +682,14 @@ impl TesseraApp {
self.emit_pointer(input, "pointerleave");
}
}
/// window_event 的 CursorMoved 在非相机拖动时调用；有捕获优先发原目标，无捕获才重新解析悬停目标。
fn move_pointer(&mut self) {
// 连续移动保留捕获，直到左键释放或取消才 take；不能因越过另一组件而重新选择接收者。
if let Some(input) = self.pointer_capture.clone() {
self.emit_pointer(input, "pointermove");
return;
}
// 计算本次订阅目标，下面只按 (session,mount) 判断悬停更换，不把每次布局版本变化都当成 leave。
let next = self.pointer_target();
if self.pointer_hover.as_ref().map(|i| (i.session, i.mount))
!= next.as_ref().map(|i| (i.session, i.mount))
@@ -681,6 +697,7 @@ impl TesseraApp {
{
self.emit_pointer(old, "pointerleave");
}
// 新/持续悬停目标收到 pointermove；本函数没有单独构造 pointerenter。
if let Some(input) = next.clone() {
self.emit_pointer(input, "pointermove");
}
@@ -688,13 +705,16 @@ impl TesseraApp {
}
/// 将标签快捷键转换为当前窗口/帧中的明确页面动作。
// handle_keyboard 处理命令+W 与 Ctrl+Tab 时调用，返回是否已构造并尝试提交有效页面动作。
fn send_tab_shortcut(&mut self, close: bool) -> bool {
let input = self.namespace.read().ok().and_then(|namespace| {
let frame = &namespace.document.frame;
if frame.session == 0 || frame.fault.is_some() || frame.tabs.is_empty() {
return None;
}
// 无显式 active 时从第一项开始；tabs 已检查非空，后续取模和前向环绕不会除零或下溢。
let active = frame.tabs.iter().position(|tab| tab.active).unwrap_or(0);
// 关闭保留当前索引，切换按 Shift 选择前一项或后一项，包含工具页在内的完整 tabs 顺序。
let index = if close {
active
} else if self.modifiers.shift_key() {
@@ -715,6 +735,7 @@ impl TesseraApp {
screen_position: None,
})
});
// 切页/关页前丢弃旧鼠标点击和键盘 click 捕获，避免释放事件落入即将变化的页面。
if let Some(input) = input {
self.guest_pressed = None;
self.guest_key = None;
@@ -726,11 +747,13 @@ impl TesseraApp {
}
/// 处理侧栏展开、工具入口和页面管理，尺寸变化还需重新发布可用视口。
// 侧栏鼠标、键盘以及命令+B 调用，UI 侧只调整宿主开合，业务页面操作仍发带版本事件。
fn sidebar_action(&mut self, action: crate::sidebar::Action) {
use crate::sidebar::Action;
match action {
Action::Toggle => {
self.sidebar.open = !self.sidebar.open;
// 折叠/展开会改变目标集合，立即取消旧捕获并更新键盘归属，视口重新发布触发布局刷新。
self.sidebar.interaction.cancel();
self.sidebar_keyboard = self.sidebar.open;
self.guest_pressed = None;
@@ -738,6 +761,7 @@ impl TesseraApp {
}
Action::NewPage => self.open_developer_tool("New tab"),
Action::Tool(name) => self.open_developer_tool(name),
// 普通页按钮携带标签数字身份，通过事件 kind 区分切页与关闭；mount 字段在此承载标签 ID。
Action::Activate(id) | Action::Close(id) => {
let input = self
.namespace
@@ -760,7 +784,7 @@ impl TesseraApp {
tab_drop: None,
screen_position: None,
});
// 滚轮优先交给可滚动挂载；未命中则尝试 3D 缩放或整页平移，最后更新开发工具自身滚动。
// 读锁成功才构造当前窗口页面事件，实际标签身份和会话有效性仍由 worker 校验。
if let Some(input) = input {
self.send_guest(input);
}
@@ -770,7 +794,9 @@ impl TesseraApp {
}
/// 在手势开始时捕获具体相机视口 ID，后续拖动保持同一目标。
// 中键、Space+左键及 3D 超阈值拖动调用，返回是否可开始手势，同时保存具体视口或整页选择。
fn begin_pan(&mut self) -> bool {
// 先清上次捕获，None 在成功返回时表示整页相机，不等于没有手势；是否激活另由 panning 保存。
self.pan_viewport = None;
let Some(point) = self.guest_point() else {
return false;
@@ -779,18 +805,22 @@ impl TesseraApp {
return false;
};
let frame = &current.document.frame;
// 优先命中允许控制的局部相机，普通 Window 没有整页平移能力，其他页面模式可使用整页手势。
self.pan_viewport = frame.camera_at(point).map(|mount| mount.id);
self.pan_viewport.is_some() || frame.surface.mode != crate::page::Mode::Window
}
/// 把窗口位移/缩放转换为捕获视口的纯数据相机事件，处理侧栏和页面视角的尺度差异。
// 拖动、触控捏合及滚轮缩放共用，向 worker 发纯数据相机操作，不在窗口线程修改托管 Camera 属性。
fn page_view(&mut self, kind: &str, delta: [f32; 2]) {
// 未捕获手势时宿主覆盖区直接拒绝，拖动已捕获则允许指针继续经过宿主区域。
if !self.panning && self.guest_covered(self.pointer) {
return;
}
let point = Point::new(self.pointer.x - self.sidebar.left(), self.pointer.y);
let input = self.namespace.read().ok().and_then(|current| {
let frame = &current.document.frame;
// 故障/无会话一律拒绝；可见边界仅约束未捕获操作，已开始拖动允许跨出页面矩形。
if frame.session == 0
|| frame.fault.is_some()
|| !self.panning
@@ -802,6 +832,7 @@ impl TesseraApp {
{
return None;
}
// 先撤销整页 Surface，局部视口收到世界点后再在运行时处理自身相机和面板映射。
let world = frame.surface.to_world(point);
// 拖动沿用捕获 ID，滚轮/缩放则按当前点命中；被捕获的视口若已消失，取消此次输入而不切换目标。
let viewport = if self.panning {
@@ -815,10 +846,12 @@ impl TesseraApp {
} else {
frame.camera_at(world)
};
// 原来捕获的是局部视口却已找不到时忽略本次移动，不降级到整页，也不改成指针下的新视口。
if self.panning && self.pan_viewport.is_some() && viewport.is_none() {
return None;
}
// 局部 2D/3D 视口使用不同动作名。平移除去页面 zoom 以还原世界位移，缩放倍率本身不按 zoom 缩放。
// 局部视口携带实际 Mount ID，动作名选择二维 pan/zoom 或三维 pan/orbit/zoom。
if let Some(viewport) = viewport {
return Some(crate::events::Input {
window: self.resource,
@@ -841,6 +874,7 @@ impl TesseraApp {
.into(),
point: Some([world.x, world.y]),
press_point: None,
// 局部平移量先除页面 zoom；缩放的第一分量是倍率不除 zoom，第二分量仍按现有转换处理。
delta: Some([
delta[0]
/ if kind == "page-pan" {
@@ -873,6 +907,7 @@ impl TesseraApp {
screen_position: None,
})
});
// 产生相机操作即撤销同次普通 click 捕获，避免拖动或缩放后释放又触发业务点击。
if let Some(input) = input {
self.guest_pressed = None;
self.send_guest(input);
@@ -880,6 +915,7 @@ impl TesseraApp {
}
/// 把已经构造的页面输入交给有界客户端，保持 GUI 线程不直接调用 VM。
// 点击、焦点、窗口/页面命令和相机输入共用发送入口；返回失败只展示队列错误，不在 GUI 同步重试执行。
fn send_guest(&mut self, event: crate::events::Input) {
if !self.event_client.send(event) {
self.developer_tools.input_error = "Native event queue is unavailable or full".into();
@@ -888,10 +924,13 @@ impl TesseraApp {
}
/// 把页面拥有焦点时的键盘动作转换为托管事件，保留按下/释放配对。
// handle_keyboard 在 guest_keyboard 路由启用时调用，当前仅处理命名 Tab/Enter/Space，普通字符不合成业务文本事件。
fn handle_guest_key(&mut self, event: &winit::event::KeyEvent) -> bool {
// 非命名键返回未消费，后续仍可被宿主快捷键或开发工具编辑路径处理。
let Key::Named(key) = &event.logical_key else {
return false;
};
// 首次 Tab 按下选下一焦点出现，抬起或系统重复只根据已有 guest_focus 决定是否消费。
if *key == NamedKey::Tab {
if event.state == ElementState::Pressed && !event.repeat {
let next = self.namespace.read().ok().and_then(|namespace| {
@@ -905,9 +944,11 @@ impl TesseraApp {
.iter()
.filter(|mount| mount.interactive)
.collect();
// 没有可交互出现就不构造 focus 事件，也不进入后面的取模索引。
if targets.is_empty() {
return None;
}
// 当前焦点令牌通过出现 ID 在本帧候选中定位；不在列表时按首次进入处理。
let current = self
.guest_focus
.as_ref()
@@ -932,6 +973,7 @@ impl TesseraApp {
screen_position: None,
})
});
// 发焦点请求前清旧键盘按下捕获，本地先保存新令牌；worker 仍检查实际合法性，发送失败会显示错误。
if let Some(next) = next {
self.guest_key = None;
self.guest_focus = Some(next.clone());
@@ -942,6 +984,7 @@ impl TesseraApp {
}
return self.guest_focus.is_some();
}
// 有页面焦点才捕获激活键，按下保存键名和焦点令牌，释放须键名匹配才发一次 click。
if matches!(key, NamedKey::Enter | NamedKey::Space) && self.guest_focus.is_some() {
if event.state == ElementState::Pressed {
if !event.repeat {
@@ -960,11 +1003,14 @@ impl TesseraApp {
}
/// 按平台窗口属性创建原生窗口、软件表面和输入法支持，再公布实际逻辑视口。
// ApplicationHandler::resumed 调用，先用局部变量完整创建窗口/上下文/表面，成功后才写回宿主字段。
fn create_native(&mut self, event_loop: &ActiveEventLoop) -> anyhow::Result<()> {
// 重复 resumed 不重复创建 OS 窗口，也不重置当前软件表面和输入状态。
if self.window.is_some() {
return Ok(());
}
// 主子窗口有不同初始标题和逻辑尺寸，共同限制最小/最大分配；运行时窗口命令随后可继续设置。
let attributes = WindowAttributes::default()
.with_title(if self.resource == crate::window::MAIN_WINDOW {
"Tessera".into()
@@ -982,6 +1028,7 @@ impl TesseraApp {
crate::window::MAX_WINDOW_DIMENSION,
));
#[cfg(target_os = "macos")]
// macOS 用全尺寸透明标题栏配合自绘侧栏，真实交通灯按钮仍由 native_chrome 对齐。
let attributes = {
use winit::platform::macos::WindowAttributesExtMacOS;
attributes
@@ -997,6 +1044,7 @@ impl TesseraApp {
let surface =
Surface::new(&context, window.clone()).map_err(|error| anyhow::anyhow!("{error}"))?;
// OS 资源都建立成功后开启 IME 并保存 Arc，Context/Surface 也持窗口句柄，避免绘制时窗口已失效。
window.set_ime_allowed(true);
self.window = Some(window.clone());
self.context = Some(context);
@@ -1009,7 +1057,9 @@ impl TesseraApp {
}
/// 停止新的交互并请求运行时清理；原生事件循环等待完成通知后退出。
// 主窗口 CloseRequested 和关闭命令调用；正常路径等待 worker ShutdownComplete，再让事件循环退出。
fn request_exit(&mut self) {
// 退出请求成功发送后置位，重复关闭不再创建第二轮清理；发送失败分支自行投递完成错误通知。
if self.exit_requested {
return;
}
@@ -1027,6 +1077,7 @@ impl TesseraApp {
}
/// 把原生应用记录的最终错误反馈给 main 的退出结果。
// main 在 run_app 返回后读取最终原生/关闭错误，不能仅凭 OS 循环结束判断应用正常退出。
pub fn exit_result(&self) -> anyhow::Result<()> {
if let Some(error) = &self.native_error {
anyhow::bail!("{error}");
@@ -1035,11 +1086,13 @@ impl TesseraApp {
}
/// 包装一次实际绘制，统一记录故障并避免对同一错误反复发送通知。
// window_event 的 RedrawRequested 调用，先做 macOS 原生按钮校正，再统一处理 try_redraw 的成功/失败状态。
fn redraw(&mut self) {
#[cfg(target_os = "macos")]
if let Some(window) = self.window.as_ref() {
crate::native_chrome::align_controls(window);
}
// 窗口/表面齐全时成功绘制清旧错误；新错误仅在文本变化时通知，避免每帧重复入错误事件。
match self.try_redraw() {
Ok(()) => {
if self.window.is_some() && self.surface.is_some() {
@@ -1057,17 +1110,21 @@ impl TesseraApp {
}
/// 读取完整发布文档，生成整窗显示列表，写入原生像素表面并呈现；错误交由外层记录。
// redraw 的实际绘制路径，先生成不可变场景再写像素；不调用 VM 业务代码或编译用户程序。
fn try_redraw(&mut self) -> anyhow::Result<()> {
// 先按现有页面粗命中和侧栏 Widget 判断手形，工具区的具体文本/调整光标在布局生成后再查询。
let guest_cursor = self.guest_hit().is_some()
|| self
.sidebar
.interaction
.hit(&self.sidebar.targets)
.is_some();
// 原生资源尚未建立时跳过，本次返回成功只表示没有可绘制目标，不代表已经 present。
let (Some(window), Some(surface)) = (self.window.as_ref(), self.surface.as_mut()) else {
return Ok(());
};
let size = window.inner_size();
// softbuffer resize 要求非零尺寸，最小化产生零轴时跳过分配和呈现。
let (Some(width), Some(height)) =
(NonZeroU32::new(size.width), NonZeroU32::new(size.height))
else {
@@ -1088,6 +1145,7 @@ impl TesseraApp {
&mut self.sidebar,
);
drop(namespace);
// 保存本次逻辑命中布局给后续输入，像素绘制使用 scene.display_list 的设备坐标。
self.layout = scene.layout;
window.set_cursor(if guest_cursor {
winit::window::CursorIcon::Pointer
@@ -1095,10 +1153,12 @@ impl TesseraApp {
self.developer_tools
.cursor_kind(&self.layout.developer_tools)
});
// 跨帧控件 reconcile 或文本选择需要额外帧时消费 repaint 标记，安排下一次原生 RedrawRequested。
if self.developer_tools.repaint {
self.developer_tools.repaint = false;
window.request_redraw();
}
// 候选窗位置来自当前逻辑输入布局，传给 winit 时仍用 LogicalPosition，不重复乘设备比例。
let ime = self
.developer_tools
.ime_position(&self.layout.developer_tools);
@@ -1111,6 +1171,7 @@ impl TesseraApp {
surface
.resize(width, height)
.map_err(|error| anyhow::anyhow!("{error}"))?;
// 取得本次目标缓冲后顺序执行整窗列表，渲染报错就不调用下面 present，不将半幅写入当作成功帧。
let mut buffer = surface
.buffer_mut()
.map_err(|error| anyhow::anyhow!("{error}"))?;
@@ -1125,6 +1186,7 @@ impl TesseraApp {
impl ApplicationHandler<AppEvent> for TesseraApp {
/// 处理 OS 直接结束事件循环的收尾，尝试在明确时限内等待运行时清理。
// winit 最终退出回调，无法再依靠 user_event 等通知；此处只做有时限的运行时关闭等待。
fn exiting(&mut self, _: &ActiveEventLoop) {
// OS 终止可能跳过 CloseRequested；此时循环已在退出，无法再等事件通知。
// 最多阻塞 5 秒等待运行时完成清理，超时保留退出错误而不无限等待。
@@ -1132,6 +1194,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
self.native_error = Some("VM worker unavailable during shutdown".into());
return;
}
// 已完成结果保留 worker 错误，尚未完成则记录超时；等待结束不代表可忽略先前原生错误。
match self.control.wait_shutdown(Duration::from_secs(5)) {
Some(outcome) => {
if let Some(error) = outcome.error {
@@ -1146,6 +1209,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
fn about_to_wait(&mut self, _event_loop: &ActiveEventLoop) {}
/// 应用获得原生活跃上下文时建立窗口，并仅在需要时请求初始页面。
// winit 活跃通知或主实例创建子资源时调用；只对主窗口首次空会话发一次 New tab 初始化。
fn resumed(&mut self, event_loop: &ActiveEventLoop) {
if self.resource == crate::window::MAIN_WINDOW
&& !self.startup_page_requested
@@ -1154,10 +1218,12 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
.read()
.is_ok_and(|n| n.runtime_session == 0 && n.document.frame.tabs.is_empty())
{
// 先标记再发送后台初始化，重入 resumed 不会重复请求；本字段不表示起始页面已执行或发布成功。
self.startup_page_requested = true;
self.developer_tools.initialize_tools("New tab");
}
// 主窗口创建失败退出事件循环，子窗口失败由主 reconcile 收集错误展示，不直接结束全部窗口。
if let Err(error) = self.create_native(event_loop) {
self.native_error = Some(format!(
"Window {} initialization failed: {error:#}",
@@ -1170,7 +1236,9 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
}
/// 处理 worker 发回的文档更新、故障和退出完成通知，不在 GUI 线程执行源回调。
// EventLoopProxy 通知入口，所有状态更改回到原生事件线程；来自工具线程的消息只带 String 和纯数据。
fn user_event(&mut self, event_loop: &ActiveEventLoop, event: AppEvent) {
// 运行时开始退出后丢弃文档/工具错误等普通消息，只让 ShutdownComplete 结束原生循环。
if self.control.is_exiting() && !matches!(&event, AppEvent::ShutdownComplete { .. }) {
return;
}
@@ -1181,6 +1249,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
}
event_loop.exit();
}
// 展示故障并撤掉普通点击/键盘激活捕获，不在此自行重建 VM 或把错误当业务页面。
AppEvent::RuntimeFailed { message } => {
self.developer_tools.input_error = message;
self.developer_tools.open = true;
@@ -1191,6 +1260,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
AppEvent::DocumentUpdated => self.document_updated(event_loop),
AppEvent::ConsoleFailed { message, source } => {
self.developer_tools.input_error = format!("Request failed: {message}");
// 仅编辑框仍为空时恢复失败发送的 source，不覆盖用户在等待网络期间新写的草稿。
if self.developer_tools.input.is_empty() {
self.developer_tools.input = source;
self.developer_tools.cursor = self.developer_tools.input.len();
@@ -1202,15 +1272,18 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
}
/// 处理原生尺寸、输入、焦点和关闭事件；先判断宿主控件，再转发页面事件。
// winit OS 事件总入口，先按 WindowId 分流，再在当前窗口处理宿主/页面输入及表面重绘。
fn window_event(
&mut self,
_event_loop: &ActiveEventLoop,
window_id: WindowId,
event: WindowEvent,
) {
// 关闭清理中不再处理尺寸或输入，防止源卸载期间又产生新的交互工作。
if self.control.is_exiting() {
return;
}
// 克隆 Arc 结束对 self.window 的借用，下面调用可变 self 方法时原生句柄仍被本事件持有。
let Some(window) = self.window.as_ref().cloned() else {
return;
};
@@ -1255,6 +1328,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
}
}
}
// 重新读取真实窗口尺寸与 DPI，发布逻辑页面约束，再等待 RedrawRequested 生成像素。
WindowEvent::Resized(_) | WindowEvent::ScaleFactorChanged { .. } => {
self.publish_viewport();
window.request_redraw();
@@ -1266,6 +1340,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
let scale = window.scale_factor() as f32;
// OS 指针是物理像素，先除 DPI 得逻辑坐标；后续侧栏命中和页面世界坐标转换都从该坐标出发。
let next = Point::new(x as f32 / scale, y as f32 / scale);
// 增量与 pointer 都是原生逻辑单位，页面相机路径会再按 Surface zoom 还原，不在这里混入世界坐标。
let delta = Point::new(next.x - self.pointer.x, next.y - self.pointer.y);
self.pointer = next;
self.sidebar
@@ -1276,6 +1351,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
&& let Some(point) = self.guest_point()
&& let Some(start) = press.point
{
// 只有按下目标仍是可控制 3D 视口才将超过阈值的移动升级为 orbit，普通按钮拖动不触发相机。
let is_3d = self.namespace.read().is_ok_and(|current| {
current.document.frame.mounts.iter().any(|mount| {
mount.id == press.mount
@@ -1290,11 +1366,13 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
self.guest_pressed = None;
}
}
// 捕获相机拖动优先消费 CursorMoved，当前事件不再推进页面 pointermove 或开发工具拖选。
if self.panning {
self.page_view("page-pan", [-delta.x, -delta.y]);
window.request_redraw();
return;
}
// 未进入相机手势才更新业务指针订阅，然后让工具更新自身悬停/拖动；二者都不直接执行 VM 回调。
self.move_pointer();
self.developer_tools.move_pointer(
next,
@@ -1318,6 +1396,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
);
window.request_redraw();
}
// 离开窗口主动取消指针捕获并停止平移，避免缺失鼠标释放后一直处于拖动状态。
WindowEvent::CursorLeft { .. } => {
self.cancel_pointer();
self.guest_pressed = None;
@@ -1332,6 +1411,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
button: MouseButton::Middle,
..
} => {
// 中键只进入平移不进入 orbit，释放时表达式令 panning=false，并撤掉普通 click 捕获。
self.orbiting = false;
self.panning = state == ElementState::Pressed && self.begin_pan();
self.guest_pressed = None;
@@ -1343,16 +1423,19 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
..
} => {
if state == ElementState::Pressed {
// 连续 pointer 订阅优先于默认 click/侧栏分流，按下捕获接收者并发 pointerdown，随后提前返回。
if let Some(input) = self.pointer_target() {
self.pointer_capture = Some(input.clone());
self.emit_pointer(input, "pointerdown");
return;
}
// 左键抬起消费原捕获并发 pointerup，这条路径不再额外合成默认 click。
} else if let Some(input) = self.pointer_capture.take() {
self.emit_pointer(input, "pointerup");
return;
}
if state == ElementState::Pressed {
// 宿主占用区域先捕获侧栏控件，只有顶部空白安全区域允许开始系统窗口拖动。
if self.sidebar.covers(self.pointer) {
self.sidebar_keyboard = true;
self.sidebar.interaction.press(&self.sidebar.targets);
@@ -1372,6 +1455,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
}
let _ = window.drag_window();
}
// Space+左键在页面区域尝试相机平移，清 click 捕获，避免拖动结束再激活组件。
} else if self.space_down && self.guest_point().is_some() {
self.orbiting = false;
self.panning = self.begin_pan();
@@ -1379,6 +1463,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
} else {
self.sidebar_keyboard = false;
self.sidebar.interaction.blur();
// 普通按下决定业务键盘归属；页面得到输入时 blur 工具，命中工具时 guest_hit 自然返回 None。
self.guest_keyboard = !self.guest_covered(self.pointer);
if self.guest_keyboard {
self.developer_tools.blur();
@@ -1398,6 +1483,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
window.request_redraw();
return;
}
// 先尝试宿主释放激活，未激活才比较页面按下/释放令牌；不能让一个抬起同时切页又发业务 click。
if let Some(action) = self.sidebar.interaction.release(&self.sidebar.targets) {
self.sidebar_action(action);
} else if let Some(pressed) = self.guest_pressed.take()
@@ -1417,6 +1503,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
}
window.request_redraw();
}
// 捏合增量转成指数缩放倍率交 page_view，捕获/覆盖和相机类型仍由统一路径判定。
WindowEvent::PinchGesture { delta, .. } => {
self.page_view("page-zoom", [(delta as f32).exp(), 0.0]);
window.request_redraw();
@@ -1430,10 +1517,12 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
p.y as f32 / window.scale_factor() as f32,
),
};
// Shift 将几乎纯纵向滚轮改成横向滚动，不覆盖用户已有明显横向分量。
if self.modifiers.shift_key() && dx.abs() < 0.1 {
dx = dy;
dy = 0.0;
}
// 侧栏范围内滚轮不穿透页面；只有展开的页面列表区改变 scroll，上限由 sidebar::draw 钳制。
if self.sidebar.covers(self.pointer) {
if self.sidebar.open && self.pointer.y >= 333.0 {
self.sidebar.scroll -= dy;
@@ -1442,6 +1531,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
return;
}
let point = self.guest_point();
// 整页 Canvas 或命中可控制局部相机都允许命令+滚轮缩放；其他页面仍先尝试内容滚动。
let canvas = self.namespace.read().is_ok_and(|n| {
n.document.frame.surface.mode == crate::page::Mode::Canvas
|| point.is_some_and(|point| n.document.frame.camera_at(point).is_some())
@@ -1451,6 +1541,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
window.request_redraw();
return;
}
// 记录当前位置是否为可控制 3D 相机，后面只有滚动容器未消费时才用它做无修饰缩放。
let scene3d = self.namespace.read().is_ok_and(|current| {
point
.and_then(|point| current.document.frame.camera_at(point))
@@ -1463,6 +1554,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
if frame.session == 0 || frame.fault.is_some() {
return None;
}
// 滚动方向取反并撤销整页 zoom，wheel_target 只选至少一轴能移动的最近祖先容器。
let delta = [-dx / frame.surface.zoom, -dy / frame.surface.zoom];
let mount = crate::scroll::wheel_target(frame, point, delta)?;
Some(crate::events::Input {
@@ -1479,11 +1571,13 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
})
})
});
// 滚动目标优先；无目标才尝试 3D 缩放，再按页面模式平移，最后工具区域自行处理滚轮。
if let Some(input) = input {
self.send_guest(input);
} else if scene3d {
self.page_view("page-zoom", [(dy * 0.005).exp().clamp(0.1, 10.), 0.]);
} else {
// Horizontal 页面在几乎无横向输入时用纵向滚轮驱动横向平移，其他情况保持两轴原方向。
let horizontal = self.namespace.read().is_ok_and(|n| {
n.document.frame.surface.mode == crate::page::Mode::Horizontal
});
@@ -1500,10 +1594,12 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
.wheel(&self.layout.developer_tools, self.pointer, dx, dy);
window.request_redraw();
}
// 预编辑只更新工具组合文本并重绘，不把未确认候选放入正式 input 或发给业务对象。
WindowEvent::Ime(Ime::Preedit(value, _)) => {
self.developer_tools.preedit = value;
window.request_redraw();
}
// 确认文本先清组合显示，只有工具打开时才走焦点对应 insert；这不是向 VM 页面发送通用文字输入。
WindowEvent::Ime(Ime::Commit(value)) => {
self.developer_tools.preedit.clear();
if self.developer_tools.open {