docs: clarify UI registration signatures and visual snapshot fields
This commit is contained in:
@@ -5,6 +5,8 @@
|
||||
//! 随后调用本模块的 `install`;运行时再通过 install_globals 注入源程序使用的 UI 值。
|
||||
//! 本文件只建立宿主环境。源程序稍后调用构造器或实例方法时,才会进入 `calls::Function::invoke`。
|
||||
//! 安装返回的 UiBridge 由运行时保存;传入的 roots 由候选运行时持有,并在失败或退役时统一释放。
|
||||
//! 安装顺序还承载 GC 关系:desktop.types 拥有类型,类型拥有工厂/方法,callable 再追踪签名和显式 captures。
|
||||
//! 两阶段补签名保留原对象身份,因此 ui 属性和 TypeConstructor 不需要重新指向另一批函数。
|
||||
use super::*;
|
||||
|
||||
/// 为一次候选程序/REPL 会话安装 Tessera 宿主环境,供运行时后续注入全局值和执行源程序。
|
||||
@@ -351,7 +353,8 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
|
||||
};
|
||||
// 初始强边是注册表;随后追加签名引用的类型,供 ContextNativeFunction::trace 使用。
|
||||
let mut captures = vec![desktop];
|
||||
// 参数和返回注解中的名义类型也是托管引用,必须纳入 captures,不能只把它们存进 Rust 签名结构。
|
||||
// ContextNativeFunction 自动追踪外壳 signature,但内部 options 不对它暴露;窄参数中的名义类型要额外加入 captures。
|
||||
// 即使 desktop.types 当前也能保活它们,仍显式枚举 options 真正使用的引用,不把内部签名藏在不可见的 Rust 拥有图中。
|
||||
captures.extend(options.references());
|
||||
vm.replace_payload(
|
||||
function,
|
||||
@@ -370,6 +373,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
|
||||
// 特殊构造器保留宽变参外壳,再由对应 Constructor 按类型字段数拆实参,返回准确 Event/ObjectList 名义类型。
|
||||
// 为返回值选取专用名义类型,避免宽变参外壳同时放宽了返回值检查。
|
||||
let kind = if name == "event" {
|
||||
// 前面已穷举通用工厂,此分支只剩 Event 和 ObjectList;这里的名字决定返回契约而不是业务实例类型。
|
||||
"Event"
|
||||
} else {
|
||||
"ObjectList"
|
||||
@@ -383,8 +387,10 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
|
||||
),
|
||||
// 固定前缀与 required 数量保持一致,额外实参由 variadic 和字段验证共同约束。
|
||||
parameters: if name == "event" {
|
||||
// Event 的事件名在外壳阶段就要求 String;随后专用构造器再拆出其余子类字段。
|
||||
vec![AnnotationType::Type.into(), AnnotationType::String.into()]
|
||||
} else {
|
||||
// ObjectList 元素和子类字段都在开放尾参中,由构造器按 requested Type 的字段声明分界。
|
||||
vec![AnnotationType::Type.into()]
|
||||
},
|
||||
variadic: Some(AnnotationType::Any.into()),
|
||||
|
||||
@@ -3,7 +3,8 @@
|
||||
//!
|
||||
//! UiBridge::dispatch 按输入 kind 分流到下面三个方法:整页、局部二维视口和局部三维场景分别处理。
|
||||
//! 它们只在所属 VM worker 上修改托管相机属性或调用 controller.update,不直接改 GUI 已发布帧。
|
||||
//! 姿态变化随后由正常依赖/快照刷新观察;任何新帧仍需走 layout/paint/commit 的完整发布路径。
|
||||
//! 姿态变化随后由正常依赖/快照刷新观察;任何新帧仍需完成布局、桥接挂载提交、绘制和稳定发布。
|
||||
//! 这三个入口由 dispatch 在信封校验与选窗检查之后调用;内部仍分别验证发布版本和该手势所需的目标/坐标字段。
|
||||
use super::*;
|
||||
|
||||
impl UiBridge {
|
||||
@@ -61,6 +62,7 @@ impl UiBridge {
|
||||
.ok_or_else(|| anyhow::anyhow!("3D controller disabled"))?;
|
||||
// 同一视觉对象的边框/内边距由快照解析,手势锚点与可用尺寸都应扣除这部分。
|
||||
let node = block::snapshot(vm.object_store(), occurrence.block)?;
|
||||
// 此处的一次性快照只用于读取盒模型,不替换 Presentation 的视觉缓存,也不提交新的布局或画面。
|
||||
// inset 将外框换算成视口内容盒,避免控制器把边框尺寸算成场景宽高。
|
||||
let inset = crate::layout::insets(&node);
|
||||
// 几何来自具体 Mount,两个窗口中共享同一场景仍可能有不同视图投影。
|
||||
@@ -198,6 +200,7 @@ impl UiBridge {
|
||||
.delta
|
||||
.ok_or_else(|| anyhow::anyhow!("viewport input has no delta"))?;
|
||||
// 基于旧快照计算三个新值,完成验证后才依次回写托管属性。
|
||||
// x/y 是世界偏移而非屏幕位移;几何先撤外层投影,除以本相机 zoom 后才属于可累加到 x/y 的单位。
|
||||
let (mut x, mut y, mut zoom) = (old.x, old.y, old.zoom);
|
||||
if input.kind == "viewport-zoom" {
|
||||
// 缩放必须有锚点,不能让缺失指针导致隐式绕视口原点缩放。
|
||||
|
||||
@@ -5,6 +5,8 @@
|
||||
//! ui_bridge::bind 也会为状态对象的绑定函数调用 operation_signature。
|
||||
//! VM 随后在调用边界读取这些签名,验证数量、类型及调用效果;业务实现位于 calls/scene3d 等模块。
|
||||
//! 参数注解并不决定是否必填:Operation::arity 给出实参数量,注解表则检查实际出现的每一个参数。
|
||||
//! 例如 Text 的注解列出 text/size/color 三项,但 arity 为 1..3,所以省略后两项合法,显式 nil 仍不满足 Number/String。
|
||||
//! ReadOnly 构造可初始化本次新分配对象;Delegated 只允许进入委托入口,后续被调用函数仍要接受各自的效果检查。
|
||||
use super::*;
|
||||
|
||||
/// bootstrap 安装实例方法时调用,构造包含 receiver 的 VM 方法契约。
|
||||
|
||||
@@ -27,6 +27,7 @@ pub struct UiNode {
|
||||
pub sizing: crate::box_model::Sizing,
|
||||
// 单边可选覆盖值;None 表示沿用 kind 的统一 padding,不代表边距为零。
|
||||
pub padding_edges: [Option<f32>; 4],
|
||||
// 四边边框厚度;layout::insets 将其与有效 padding 相加,内容盒、相机锚点及绘制共用该内缩量。
|
||||
pub border: crate::layout::Insets,
|
||||
// 留原始颜色字符串供显示列表解码;颜色变更也必须使 shallow_eq 为 false。
|
||||
pub border_color: String,
|
||||
@@ -86,6 +87,7 @@ impl UiNode {
|
||||
}
|
||||
|
||||
/// model::snapshot 缓存重建节点后调用,判断可否保留旧 Arc;返回 true 不会修改任何节点或 VM 对象。
|
||||
/// 缓存调用方仍会用本轮读取重建依赖/父边;这里只证明视觉值可复用,不能证明依赖来源没有变化。
|
||||
pub fn shallow_eq(&self, other: &Self) -> bool {
|
||||
// 先比较所有公共视觉/协议配置,任一变化都不能复用旧节点 Arc,即使子内容完全相同。
|
||||
if self.surface != other.surface
|
||||
@@ -286,13 +288,18 @@ pub enum UiKind {
|
||||
},
|
||||
// 旧 Page Canvas 模式的兼容投影,位置数组与孩子顺序一致,页面级 Surface 保存其相机。
|
||||
Canvas {
|
||||
// 页面根中每个孩子的业务位置,保持与 children 同长度同顺序;Surface 再统一变换到页面视图。
|
||||
positions: Vec<[f32; 2]>,
|
||||
// 业务组成提取的不可变子树;数组顺序决定遍历/绘制顺序,不按 x/y 自动排序。
|
||||
children: Vec<Arc<UiNode>>,
|
||||
},
|
||||
// 按钮是有子内容的容器,不把标签文本硬编码进 UiKind;交互资格另由 UiNode 标志表达。
|
||||
Button {
|
||||
// 内容与边框之间的统一内边距;单边覆盖仍优先使用 UiNode.padding_edges。
|
||||
padding: f32,
|
||||
// 多个内容孩子的主轴间距,不含父节点外 margin 或按钮边框厚度。
|
||||
gap: f32,
|
||||
// 标签只是其中一个普通 Text 子树,按钮没有独立的硬编码文字字段。
|
||||
children: Vec<Arc<UiNode>>,
|
||||
},
|
||||
// 文字叶节点保留源字号等级与颜色文本;排版及最终设备比例由后续布局/显示列表转换处理。
|
||||
@@ -306,20 +313,30 @@ pub enum UiKind {
|
||||
},
|
||||
// 纯绘制叶节点;几何尺寸与圆角供布局/显示列表共用,不含托管对象句柄。
|
||||
Rect {
|
||||
// 自然宽高用于测量;父安排与盒尺寸策略仍可给实际出现分配其他尺寸。
|
||||
width: f32,
|
||||
height: f32,
|
||||
// 圆角半径影响显示列表的矩形命令,不给孩子增加布局空间。
|
||||
radius: f32,
|
||||
// 已校验格式的填充色字符串,与 UiNode.border_color 分别控制填充和边框。
|
||||
color: String,
|
||||
},
|
||||
// Column 沿纵轴累加孩子位置,Row 沿横轴;二者都保存统一内边距和孩子间距。
|
||||
Column {
|
||||
// 容器默认内边距,最终内容内缩还包括单边覆盖与边框厚度。
|
||||
padding: f32,
|
||||
// 相邻孩子间沿纵向增加的空隙,首尾不额外增加一份 gap。
|
||||
gap: f32,
|
||||
// 当前组成顺序;节点可共享 Arc,但每次出现的 Mount 和几何另行建立。
|
||||
children: Vec<Arc<UiNode>>,
|
||||
},
|
||||
// 横排容器与 Column 使用相同盒模型,但 gap 和弹性分配沿水平主轴计算。
|
||||
Row {
|
||||
// 统一内边距,由 layout::insets 与单边覆盖/边框合成有效值。
|
||||
padding: f32,
|
||||
// 横向相邻孩子间距,不是孩子自身宽度或两边 margin 的替代值。
|
||||
gap: f32,
|
||||
// 源组成的逻辑顺序,不因视觉位置变化而重排 slot。
|
||||
children: Vec<Arc<UiNode>>,
|
||||
},
|
||||
// 无视觉内容的间隔叶节点,提供布局占用尺寸。
|
||||
@@ -328,10 +345,14 @@ pub enum UiKind {
|
||||
Scroll {
|
||||
// axis 指定允许消费的滚动方向;实际可消费距离还取决于具体 Mount 的内容/视口范围。
|
||||
axis: crate::scroll::Axis,
|
||||
// 有限视口的自然尺寸;内容可能大于视口,溢出范围和偏移由布局与 Mount 派生。
|
||||
width: f32,
|
||||
height: f32,
|
||||
// 内容布局的统一内边距,与视口外 margin 分开。
|
||||
padding: f32,
|
||||
// 内容子项的纵向间隔,保持与原生滚动容器布局规则一致。
|
||||
gap: f32,
|
||||
// 当前内容树;滚动仅改变出现投影,不把移动后的坐标写入共享 UiNode。
|
||||
children: Vec<Arc<UiNode>>,
|
||||
},
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user