docs: explain Tessera modules and execution flows in Chinese
This commit is contained in:
@@ -1,6 +1,10 @@
|
||||
//! 安装一次 VM 域需要的宿主类型、对象和方法。类型注册表是源代码调用原生能力的入口。
|
||||
//! 先建立类型与桌面基础设施,再绑定构造器、视觉协议和开发工具工厂;返回的根负责保持这些对象存活。
|
||||
//!
|
||||
//! Allocate and connect the managed desktop, type tables and host globals.
|
||||
use super::*;
|
||||
|
||||
/// 把本模块的类型、方法或能力注册到所属运行时上下文。
|
||||
pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
|
||||
let desktop = vm.new_object()?;
|
||||
roots.push(desktop);
|
||||
|
||||
@@ -1,14 +1,20 @@
|
||||
//! 把 Endor 方法调用分派到对应宿主操作。这里处理构造、树修改、绑定、状态与页面能力。
|
||||
//! 先检查参数和只读阶段限制,再修改托管状态;对象引用的生命周期仍交给 NativeContext 和 Aster 管理。
|
||||
//!
|
||||
//! Native Block operations executed on the owning VM worker.
|
||||
use super::*;
|
||||
|
||||
impl NativeCallable for Function {
|
||||
/// 给出参数与返回值的托管类型契约;实际操作在 invoke 中执行。
|
||||
fn signature(&self) -> Option<CallSignature> {
|
||||
self.signature.clone()
|
||||
}
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||||
Some(self.operation.arity())
|
||||
}
|
||||
|
||||
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
|
||||
use Operation::*;
|
||||
let arity = self.operation.arity();
|
||||
|
||||
@@ -1,15 +1,20 @@
|
||||
//! 把内置开发工具和起始页接入托管 Page。工厂在所属 VM 中编译和执行,而不是在窗口线程另建业务状态。
|
||||
//!
|
||||
//! Developer workspaces are managed Pages, using the same roots and placement API.
|
||||
use super::*;
|
||||
|
||||
#[derive(Debug)]
|
||||
/// 工具打开能力,保存所属会话和 ui 对象;调用时校验工具名,再在该 VM 中展示页面。
|
||||
struct OpenTool {
|
||||
session: Shared,
|
||||
ui: ObjectRef,
|
||||
}
|
||||
impl NativeCallable for OpenTool {
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||||
Some(endor_core::CallArity::exact(1))
|
||||
}
|
||||
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
|
||||
let [Value::Text(name)] = args else {
|
||||
return Err(invalid("developerTools requires a tool name"));
|
||||
@@ -63,6 +68,7 @@ impl NativeCallable for OpenTool {
|
||||
Ok(NativeResult::Return(Value::Object(page)))
|
||||
}
|
||||
}
|
||||
/// 把本模块的类型、方法或能力注册到所属运行时上下文。
|
||||
pub(super) fn install(vm: &mut Vm, ui: ObjectRef, session: &Shared) -> Result<()> {
|
||||
let function = vm.allocate(ContextNativeFunction::new(
|
||||
"developerTools",
|
||||
@@ -79,6 +85,7 @@ pub(super) fn install(vm: &mut Vm, ui: ObjectRef, session: &Shared) -> Result<()
|
||||
|
||||
/// Compile the bundled Endor page once per VM, in a private module namespace.
|
||||
/// Its functions/classes and callbacks remain ordinary managed VM objects.
|
||||
/// 编译并安装 VM 私有的起始页工厂,供新页面动作重复调用。
|
||||
pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> {
|
||||
let source = frontend::EndorReader::from_text(
|
||||
"tessera:start-page.endor",
|
||||
|
||||
@@ -1,7 +1,11 @@
|
||||
//! 把页面、2D 视口和 3D 视口的相机输入转换成托管对象更新。
|
||||
//! 输入携带具体出现的 Mount;嵌套世界 UI 先做逆投影,避免把屏幕位移直接当成场景坐标。
|
||||
//!
|
||||
//! Camera mutations run on the owning VM worker, just like other page input.
|
||||
use super::*;
|
||||
|
||||
impl UiBridge {
|
||||
/// 解码指定 3D 视口的旋转/平移/缩放输入,再调用其托管相机控制器。
|
||||
pub(super) fn dispatch_scene_view(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -108,6 +112,7 @@ impl UiBridge {
|
||||
result
|
||||
}
|
||||
|
||||
/// 把具体 CanvasViewport 的位移或缩放锚点映射到其显式 Camera2D。
|
||||
pub(super) fn dispatch_viewport_view(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -197,6 +202,7 @@ impl UiBridge {
|
||||
result
|
||||
}
|
||||
|
||||
/// 处理旧 Page 模式的兼容相机事件;独立视口使用各自的输入路径。
|
||||
pub(super) fn dispatch_page_view(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
//! 声明宿主方法在 Endor 类型系统中的参数和返回契约。
|
||||
//! 签名用于构造/调用检查,应与 calls 和各 NativeCallable 实现保持一致;这里不执行实际业务操作。
|
||||
//!
|
||||
//! Canonical contracts for native Block methods and constructors.
|
||||
use super::*;
|
||||
|
||||
/// 根据宿主方法类别提供 Endor 方法的签名,供类型与调用检查使用。
|
||||
pub(super) fn method_signature(
|
||||
store: &endor_core::ObjectStore,
|
||||
desktop: ObjectRef,
|
||||
@@ -86,6 +90,7 @@ pub(super) fn method_signature(
|
||||
Ok(signature)
|
||||
}
|
||||
|
||||
/// 将具体宿主 Operation 映射到参数/返回类型契约。
|
||||
pub(super) fn operation_signature(
|
||||
store: &endor_core::ObjectStore,
|
||||
desktop: ObjectRef,
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
// The page, cards and actions belong to Endor. The host only owns its sidebar.
|
||||
// 默认页由真实 Endor 对象组成:宿主负责窗口和侧栏,卡片布局、绘制和按钮回调在源代码中定义。
|
||||
// Note 复用 Column 的内容测量,但固定卡片宽度;paint 只提供背景,孩子仍沿正常树绘制。
|
||||
class Note: Column {
|
||||
tint: String
|
||||
function measure(self: Note, mount: Mount, constraints: Constraints): MeasureResult {
|
||||
@@ -18,12 +20,15 @@ class Note: Column {
|
||||
}
|
||||
}
|
||||
class QuietButton: Button {
|
||||
// 返回空绘制列表保留 Button 的交互能力,同时让这个入口只显示孩子文字。
|
||||
function paint(self: QuietButton, mount: Mount, geometry: Bounds): DisplayList {
|
||||
return DisplayList(ObjectList())
|
||||
}
|
||||
}
|
||||
class StartActions {
|
||||
// 保存起始页面身份,子页面中的返回按钮激活同一 Page,而不是复制一份页面。
|
||||
home: Page
|
||||
// 窗口页面是普通有限 Column;可用区域来自宿主发布的逻辑视口。
|
||||
function blank(self: StartActions, event: Event): Unit {
|
||||
page = Page()
|
||||
page.title = "窗口页面"
|
||||
@@ -31,6 +36,7 @@ class StartActions {
|
||||
back.onClick(self.home.activate)
|
||||
page.render(Column(56, 20, TextBlock("恰好一个窗口", 3), TextBlock("页面跟随可用区域调整。内容和工具栏由 Endor 自己组织。"), back))
|
||||
}
|
||||
// 延伸方向属于容器与滚动组合:Column 安排内容,有限 ScrollBlock 控制可见范围。
|
||||
function vertical(self: StartActions, event: Event): Unit {
|
||||
page = Page()
|
||||
page.title = "纵向页面"
|
||||
@@ -45,6 +51,7 @@ class StartActions {
|
||||
page.crossAlign = "stretch"
|
||||
page.render(view)
|
||||
}
|
||||
// Row 内可继续放 Column 卡片;横向滚动不要求改变 Page 的身份或生命周期。
|
||||
function horizontal(self: StartActions, event: Event): Unit {
|
||||
page = Page()
|
||||
page.title = "横向页面"
|
||||
@@ -59,9 +66,11 @@ class StartActions {
|
||||
page.crossAlign = "stretch"
|
||||
page.render(view)
|
||||
}
|
||||
// 重新调用工厂得到独立页面与相机,已有画布继续保留自己的视角。
|
||||
function canvas(self: StartActions, event: Event): Unit {
|
||||
page = newTab()
|
||||
}
|
||||
// 两个文字绑定观察同一个状态对象,示范共享业务状态与多个展示位置的区别。
|
||||
function counter(self: StartActions, event: Event): Unit {
|
||||
count = ui.state(0)
|
||||
add = Button("增加计数")
|
||||
@@ -71,6 +80,7 @@ class StartActions {
|
||||
page.render(Column(48, 24, TextBlock("一个对象,两个视图", 2), Row(0, 32, ui.textOf(count, "value", 3), ui.textOf(count, "value", 3)), add))
|
||||
}
|
||||
}
|
||||
// 页面工厂:先建立业务对象/动作,再建立世界组成,最后用一个有限视口显示它。
|
||||
function newTab(): Page {
|
||||
page = Page()
|
||||
page.title = "自由画布"
|
||||
@@ -86,6 +96,7 @@ function newTab(): Page {
|
||||
canvas.on("click", actions.canvas)
|
||||
shared.on("click", actions.counter)
|
||||
hero = Column(0, 16, TextBlock("给想法,一点空间。", 3, "#303941"), TextBlock("页面可以是一扇窗口,也可以一直延伸。", 1, "#7D858C"), Spacer(8), Row(0, 10, fixed, vertical), Row(0, 10, horizontal, canvas), shared)
|
||||
// x/y 属于 Scene2D 子组件的世界位置;卡片内部依旧由普通 Row/Column 排版。
|
||||
hero.x = 316
|
||||
hero.y = 254
|
||||
world = Scene2D(hero)
|
||||
@@ -109,6 +120,7 @@ function newTab(): Page {
|
||||
end.x = 716
|
||||
end.y = 614
|
||||
world.append(end)
|
||||
// 视口参加有限布局并占用剩余空间;移动它的 Camera2D 不改写卡片世界位置。
|
||||
view = CanvasViewport(1024, 800, world)
|
||||
view.flex = 1
|
||||
page.crossAlign = "stretch"
|
||||
|
||||
@@ -1,8 +1,13 @@
|
||||
//! 定义从托管对象提取的不可变视觉树。共享业务对象可以有多次展示,树节点与 Mount 出现的身份不是同一概念。
|
||||
//! 节点保存排版、绘制和协议投影信息;浅比较用于决定是否复用已有快照。
|
||||
//!
|
||||
//! Owned immutable visual derivation; no managed VM handles.
|
||||
use std::sync::Arc;
|
||||
|
||||
#[derive(Debug, Clone, PartialEq)]
|
||||
/// 不可变视觉节点。block_id 关联业务身份,slots 保留子项出现的稳定组成;kind 和盒模型字段用于派生排版与绘制。
|
||||
pub struct UiNode {
|
||||
// 只有页面根带兼容 Page 相机;其余字段是普通有限盒子的布局策略。
|
||||
pub surface: Option<crate::page::Surface>,
|
||||
pub flex: f32,
|
||||
pub flex_policy: crate::layout::FlexPolicy,
|
||||
@@ -15,14 +20,17 @@ pub struct UiNode {
|
||||
pub border: crate::layout::Insets,
|
||||
pub border_color: String,
|
||||
pub clip_children: bool,
|
||||
// 这些字符串只是派生身份/协议版本键,不是可以操作托管堆的 ObjectRef。
|
||||
pub block_id: String,
|
||||
pub protocol_key: String,
|
||||
// slot 保持组成身份;数组次序确定当前绘制/布局顺序,二者不是同一概念。
|
||||
pub slots: Vec<u64>,
|
||||
pub interactive: bool,
|
||||
pub kind: UiKind,
|
||||
}
|
||||
|
||||
impl UiNode {
|
||||
/// 按节点种类返回其视觉子项;叶节点使用空切片,避免为遍历另建组成。
|
||||
pub fn children(&self) -> &[Arc<UiNode>] {
|
||||
match &self.kind {
|
||||
UiKind::Column { children, .. }
|
||||
@@ -38,6 +46,7 @@ impl UiNode {
|
||||
}
|
||||
}
|
||||
|
||||
/// 判断是否需要对子项执行弹性主轴分配。
|
||||
pub fn has_flex(&self) -> bool {
|
||||
self.flex > 0.0
|
||||
|| self.flex_policy != crate::layout::FlexPolicy::default()
|
||||
@@ -45,6 +54,7 @@ impl UiNode {
|
||||
|| self.sizing.height == crate::box_model::Dimension::Fill
|
||||
}
|
||||
|
||||
/// 判断当前节点是否会为子项指定实际分配范围,供源布局选择安排路径。
|
||||
pub fn allocates_children(&self) -> bool {
|
||||
self.children().iter().any(|child| {
|
||||
child.has_flex()
|
||||
@@ -53,6 +63,7 @@ impl UiNode {
|
||||
})
|
||||
}
|
||||
|
||||
/// 比较节点自身配置和直接子项身份,决定能否复用旧 Arc;不是深拷贝业务图。
|
||||
pub fn shallow_eq(&self, other: &Self) -> bool {
|
||||
if self.surface != other.surface
|
||||
|| self.flex_policy != other.flex_policy
|
||||
@@ -198,6 +209,7 @@ impl UiNode {
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq)]
|
||||
/// 视觉内容的原生分类。叶节点保存绘制数据,容器保存子树,场景视口另外保存相机与世界投影。
|
||||
pub enum UiKind {
|
||||
Viewport3D {
|
||||
width: f32,
|
||||
|
||||
Reference in New Issue
Block a user