docs: explain Tessera modules and execution flows in Chinese
This commit is contained in:
@@ -1,2 +1,4 @@
|
||||
//! 语言桥接模块入口。集中导出 Endor 类型和宿主实现之间的适配层。
|
||||
//!
|
||||
// Module ownership follows the directory; crate-root aliases keep internal call sites stable.
|
||||
pub(crate) mod ui_bridge;
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
//! Endor 与 Tessera 的展示事务协调层:维护每个窗口的 Page、Mount、布局缓存和发布版本。
|
||||
//! Session 保存托管对象的展示上下文;跨线程发布的是不可变 UiNode/Frame,而不是可以在窗口线程执行的 VM。
|
||||
//! 刷新按 prepare → layout → paint → commit 推进。挂起工作必须恢复或显式取消;失败不能把未完成的几何和生命周期状态留作已发布结果。
|
||||
//!
|
||||
//! Tessera's native visual protocols over Aster's managed object graph.
|
||||
mod bootstrap;
|
||||
mod calls;
|
||||
@@ -90,6 +94,7 @@ pub const QUERY_NAMES: &[&str] = &[
|
||||
pub use tree::{UiKind, UiNode};
|
||||
|
||||
#[derive(Debug)]
|
||||
/// 整个 VM 的桥接会话。节点索引跨窗口共享,presentations 按窗口隔离派生状态;current 决定方法当前访问哪份展示上下文。
|
||||
struct Session {
|
||||
// Weak visual-object registry belongs to the VM, not a particular window.
|
||||
nodes: Vec<WeakObjectRef>,
|
||||
@@ -109,6 +114,7 @@ struct Session {
|
||||
}
|
||||
|
||||
impl Session {
|
||||
/// 收集所有窗口的私有 desktop 身份,用于排除宿主记账读取造成的无关布局失效。
|
||||
fn host_desktops(&self) -> std::collections::HashSet<ObjectRef> {
|
||||
self.presentations
|
||||
.values()
|
||||
@@ -119,6 +125,7 @@ impl Session {
|
||||
|
||||
impl std::ops::Deref for Session {
|
||||
type Target = crate::presentation::Presentation;
|
||||
/// 将包装类型的只读访问转交给内部当前上下文。
|
||||
fn deref(&self) -> &Self::Target {
|
||||
self.presentations
|
||||
.get(&self.current)
|
||||
@@ -126,6 +133,7 @@ impl std::ops::Deref for Session {
|
||||
}
|
||||
}
|
||||
impl std::ops::DerefMut for Session {
|
||||
/// 将包装类型的可变访问转交给内部当前上下文。
|
||||
fn deref_mut(&mut self) -> &mut Self::Target {
|
||||
self.presentations
|
||||
.get_mut(&self.current)
|
||||
@@ -135,6 +143,7 @@ impl std::ops::DerefMut for Session {
|
||||
type Shared = Arc<Mutex<Session>>;
|
||||
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
/// ui/组件宿主入口的操作枚举;统一由调用适配器分派,不直接代表已经发生的业务变更。
|
||||
enum Operation {
|
||||
IsInstance,
|
||||
Implement,
|
||||
@@ -202,6 +211,7 @@ enum Operation {
|
||||
}
|
||||
|
||||
impl Operation {
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
fn arity(self) -> endor_core::CallArity {
|
||||
use Operation::*;
|
||||
let (minimum, maximum) = match self {
|
||||
@@ -238,6 +248,7 @@ impl Operation {
|
||||
}
|
||||
|
||||
#[derive(Debug)]
|
||||
/// 将一个宿主 Operation 及会话环境封装成 VM 可调用对象。
|
||||
struct Function {
|
||||
signature: Option<CallSignature>,
|
||||
operation: Operation,
|
||||
@@ -249,6 +260,7 @@ struct Function {
|
||||
/// One shared implementation on the nominal type. The VM binds receivers;
|
||||
/// individual Blocks no longer allocate owner-capturing method closures.
|
||||
#[derive(Debug)]
|
||||
/// 类型查询/能力方法的原生包装,保存调用所需的声明与会话。
|
||||
struct TypeMethod {
|
||||
signature: CallSignature,
|
||||
operation: Operation,
|
||||
@@ -256,6 +268,7 @@ struct TypeMethod {
|
||||
session: Shared,
|
||||
}
|
||||
|
||||
/// 判断方法是否仍为宿主提供的原生事件实现,区分它与用户源覆盖。
|
||||
pub(crate) fn is_intrinsic_event(
|
||||
store: &endor_core::ObjectStore,
|
||||
function: ObjectRef,
|
||||
@@ -274,9 +287,11 @@ pub(crate) fn is_intrinsic_event(
|
||||
}
|
||||
|
||||
impl NativeCallable for TypeMethod {
|
||||
/// 给出参数与返回值的托管类型契约;实际操作在 invoke 中执行。
|
||||
fn signature(&self) -> Option<CallSignature> {
|
||||
Some(self.signature.clone())
|
||||
}
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||||
let arity = self.operation.arity();
|
||||
Some(endor_core::CallArity::range(
|
||||
@@ -285,6 +300,7 @@ impl NativeCallable for TypeMethod {
|
||||
))
|
||||
}
|
||||
|
||||
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
|
||||
let owner = object(args.first())?;
|
||||
if !cx.store().is_instance(owner, self.expected)? {
|
||||
@@ -304,6 +320,7 @@ impl NativeCallable for TypeMethod {
|
||||
/// The Type dispatcher passes the requested subclass explicitly. Native
|
||||
/// constructor options precede the subclass's inherited/own field arguments.
|
||||
#[derive(Debug)]
|
||||
/// 为源代码调用原生类型构造器提供受检查的分配入口。
|
||||
struct NativeFactory {
|
||||
signature: Option<CallSignature>,
|
||||
options: Option<CallSignature>,
|
||||
@@ -312,9 +329,11 @@ struct NativeFactory {
|
||||
}
|
||||
|
||||
impl NativeCallable for NativeFactory {
|
||||
/// 给出参数与返回值的托管类型契约;实际操作在 invoke 中执行。
|
||||
fn signature(&self) -> Option<CallSignature> {
|
||||
self.signature.clone()
|
||||
}
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||||
Some(endor_core::CallArity::range(
|
||||
self.operation.arity().required + 1,
|
||||
@@ -322,6 +341,7 @@ impl NativeCallable for NativeFactory {
|
||||
))
|
||||
}
|
||||
|
||||
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
|
||||
let requested = object(args.first())?;
|
||||
let fields = cx
|
||||
@@ -367,21 +387,25 @@ impl NativeCallable for NativeFactory {
|
||||
}
|
||||
}
|
||||
|
||||
/// 统一构造本模块的参数错误,让调用方停止处理无效输入。
|
||||
fn invalid(message: &'static str) -> VmError {
|
||||
VmError::InvalidArgument(message)
|
||||
}
|
||||
/// 从源值中提取并检查托管对象身份,错误类型沿 VM 错误返回。
|
||||
fn object(value: Option<&Value>) -> Result<ObjectRef, VmError> {
|
||||
match value {
|
||||
Some(Value::Object(value)) => Ok(*value),
|
||||
_ => Err(invalid("expected an object")),
|
||||
}
|
||||
}
|
||||
/// 把当前源值或文本选择解码成此调用需要的文本表示。
|
||||
fn text(value: Option<&Value>) -> Result<String, VmError> {
|
||||
match value {
|
||||
Some(Value::Text(value)) => Ok(value.clone()),
|
||||
_ => Err(invalid("expected text")),
|
||||
}
|
||||
}
|
||||
/// 读取整数参数,拒绝非整数或无法在目标范围表示的值。
|
||||
fn integer(value: Option<&Value>) -> Result<u64, VmError> {
|
||||
match value {
|
||||
Some(Value::Number(value)) => value
|
||||
@@ -391,6 +415,7 @@ fn integer(value: Option<&Value>) -> Result<u64, VmError> {
|
||||
_ => Err(invalid("expected a nonnegative integer")),
|
||||
}
|
||||
}
|
||||
/// 解析颜色值并检查其满足当前原生绘制约定。
|
||||
fn color(value: Option<&Value>, default: &str) -> Result<String, VmError> {
|
||||
let value = value
|
||||
.map(|v| text(Some(v)))
|
||||
@@ -399,6 +424,7 @@ fn color(value: Option<&Value>, default: &str) -> Result<String, VmError> {
|
||||
parse_color(&value).map_err(|_| invalid("color must use #RRGGBB or #RRGGBBAA"))?;
|
||||
Ok(value)
|
||||
}
|
||||
/// 读取布局尺寸参数,检查非负、有限和最大尺寸限制。
|
||||
fn dimension(value: Option<&Value>) -> Result<f32, VmError> {
|
||||
let Some(Value::Number(number)) = value else {
|
||||
return Err(invalid("expected a finite nonnegative dimension"));
|
||||
@@ -414,6 +440,7 @@ fn dimension(value: Option<&Value>) -> Result<f32, VmError> {
|
||||
Ok(value as f32)
|
||||
}
|
||||
|
||||
/// 为一个托管对象安装绑定到当前会话的原生方法,声明调用名与具体 Operation。
|
||||
fn bind(
|
||||
cx: &mut NativeContext<'_>,
|
||||
owner: ObjectRef,
|
||||
@@ -440,6 +467,7 @@ fn bind(
|
||||
cx.set_attr(owner, name, Value::Object(function))
|
||||
}
|
||||
|
||||
/// 使用默认原生类型创建 Block;需要源子类身份的构造走 new_typed_block。
|
||||
fn new_block(
|
||||
cx: &mut NativeContext<'_>,
|
||||
data: Data,
|
||||
@@ -448,6 +476,7 @@ fn new_block(
|
||||
new_typed_block(cx, data, session, None)
|
||||
}
|
||||
|
||||
/// 分配有名义类型和默认位置/缩放的独立相机,供新视口拥有自己的导航状态。
|
||||
fn new_camera2d(
|
||||
cx: &mut NativeContext<'_>,
|
||||
session: &Shared,
|
||||
@@ -473,6 +502,7 @@ fn new_camera2d(
|
||||
Ok(camera)
|
||||
}
|
||||
|
||||
/// 创建原生 Block 并附加请求的 Endor 类型;先验证继承关系,再登记到会话节点索引。
|
||||
fn new_typed_block(
|
||||
cx: &mut NativeContext<'_>,
|
||||
data: Data,
|
||||
@@ -528,6 +558,7 @@ fn new_typed_block(
|
||||
Ok(block)
|
||||
}
|
||||
|
||||
/// 在当前 VM 中建立窗口、desktop 和独立 Presentation,实际 OS 窗口等命令发布后再创建。
|
||||
fn create_window(
|
||||
cx: &mut NativeContext<'_>,
|
||||
state: &mut Session,
|
||||
@@ -557,6 +588,7 @@ fn create_window(
|
||||
Ok(window)
|
||||
}
|
||||
|
||||
/// 从页面登记信息取得所属窗口,保持 Page 的归属与原生资源身份一致。
|
||||
fn page_window(
|
||||
store: &endor_core::ObjectStore,
|
||||
state: &Session,
|
||||
@@ -570,6 +602,7 @@ fn page_window(
|
||||
}
|
||||
Ok(None)
|
||||
}
|
||||
/// 撤销页面在展示会话中的登记,配合模型层处理活动页面与生命周期。
|
||||
fn remove_page(
|
||||
cx: &mut NativeContext<'_>,
|
||||
view: &mut crate::presentation::Presentation,
|
||||
@@ -588,6 +621,7 @@ fn remove_page(
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
/// 在指定窗口安排页面展示,并维护目标 Presentation 的活动/待发布状态。
|
||||
fn show_in(
|
||||
cx: &mut NativeContext<'_>,
|
||||
page: ObjectRef,
|
||||
@@ -638,20 +672,24 @@ fn show_in(
|
||||
view.pending = Some(Some(page));
|
||||
Ok(())
|
||||
}
|
||||
/// 在当前窗口安排页面展示,实际几何和画面由后续刷新提交。
|
||||
fn show(cx: &mut NativeContext<'_>, page: ObjectRef, session: &Shared) -> Result<(), VmError> {
|
||||
show_in(cx, page, session, None)
|
||||
}
|
||||
|
||||
#[derive(Debug)]
|
||||
/// 接收源 present 结果并将其转换成宿主可展示内容的原生续接步骤。
|
||||
struct PresentResult {
|
||||
open: bool,
|
||||
session: Shared,
|
||||
}
|
||||
impl NativeCallable for PresentResult {
|
||||
/// 声明宿主可调用对象接受的参数个数,供 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::Object(root)] = args else {
|
||||
return Err(invalid("Presentable.present must return a Block"));
|
||||
@@ -676,6 +714,7 @@ impl NativeCallable for PresentResult {
|
||||
}
|
||||
}
|
||||
|
||||
/// 根据 Presentable 能力把任意源值转换成可展示内容,避免只允许某个原生 Block 类型。
|
||||
fn present_value(
|
||||
cx: &mut NativeContext<'_>,
|
||||
value: &Value,
|
||||
@@ -718,11 +757,13 @@ fn present_value(
|
||||
}
|
||||
|
||||
#[must_use = "pending layout must be resumed on its owning VM"]
|
||||
/// 桥接布局的挂起/完成结果;PendingLayout 必须与其窗口上下文一起继续处理。
|
||||
pub enum LayoutProgress {
|
||||
Pending(Box<PendingLayout>),
|
||||
Complete(Box<crate::document::Frame>),
|
||||
}
|
||||
|
||||
/// 一次未提交布局的上下文:目标窗口、根、布局/缓存、延后钩子以及用于失败恢复的检查点。
|
||||
struct LayoutContext {
|
||||
surface: crate::page::Surface,
|
||||
root: Arc<UiNode>,
|
||||
@@ -734,17 +775,20 @@ struct LayoutContext {
|
||||
checkpoint: crate::mount::Checkpoint,
|
||||
}
|
||||
|
||||
/// 挂起布局的拥有者。续体与上下文必须一起保留并最终恢复或取消。
|
||||
pub struct PendingLayout {
|
||||
work: crate::source_layout::Work,
|
||||
context: LayoutContext,
|
||||
}
|
||||
|
||||
/// 运行时持有的桥接能力句柄,通过共享 Session 协调托管对象与每窗口展示。
|
||||
pub struct UiBridge {
|
||||
pub ui: ObjectRef,
|
||||
session: Shared,
|
||||
tasks: crate::tasks::Scheduler,
|
||||
}
|
||||
|
||||
/// 解析对象的方法并在同一 VM 中调用,使源覆盖与原生成员共用方法查找规则。
|
||||
fn invoke_member(
|
||||
vm: &mut Vm,
|
||||
owner: ObjectRef,
|
||||
@@ -770,6 +814,7 @@ fn invoke_member(
|
||||
result
|
||||
}
|
||||
|
||||
/// 将托管页面注册表投影成稳定标签 ID、标题与活动状态,不把托管引用交给原生侧栏。
|
||||
fn project_tabs(
|
||||
vm: &Vm,
|
||||
state: &mut crate::presentation::Presentation,
|
||||
@@ -816,6 +861,7 @@ fn project_tabs(
|
||||
impl UiBridge {
|
||||
/// Detach all occurrences without running layout/paint. All windows are
|
||||
/// already closed before source unmount hooks run, so they cannot remount.
|
||||
/// 按窗口和展示生命周期执行有界退出清理,允许调用方根据故障状态决定是否执行回调。
|
||||
pub fn shutdown(&self, vm: &mut Vm, callbacks: bool) -> Result<(usize, usize, usize)> {
|
||||
let tasks = self.tasks.quiesce(vm)?;
|
||||
let mut drivers = Vec::new();
|
||||
@@ -885,16 +931,20 @@ impl UiBridge {
|
||||
result
|
||||
}
|
||||
|
||||
/// 查询任务系统是否仍有可推进的协作工作,供 worker 选择等待策略。
|
||||
pub fn has_cooperative_tasks(&self) -> bool {
|
||||
self.tasks.has_cooperative_work()
|
||||
}
|
||||
|
||||
/// 把当前 VM 交给任务调度器推进,限制一轮交付数量。
|
||||
pub fn poll_tasks(&self, vm: &mut Vm, limit: usize) -> Result<usize> {
|
||||
self.tasks.poll(vm, limit)
|
||||
}
|
||||
/// 取消当前域中的任务,撤销关闭/失败后不应再发生的交付。
|
||||
pub fn cancel_tasks(&self, vm: &mut Vm) -> Result<usize> {
|
||||
self.tasks.cancel_all(vm)
|
||||
}
|
||||
/// 返回当前仍有效的展示窗口身份,用于稳定遍历一次全窗口刷新。
|
||||
pub fn window_ids(&self) -> Result<Vec<u64>> {
|
||||
let state = self
|
||||
.session
|
||||
@@ -917,6 +967,7 @@ impl UiBridge {
|
||||
});
|
||||
Ok(ids)
|
||||
}
|
||||
/// 判断窗口是否仍登记且没有进入关闭状态。
|
||||
pub fn accepts_window(&self, id: u64) -> bool {
|
||||
self.session.lock().is_ok_and(|state| {
|
||||
state
|
||||
@@ -926,6 +977,7 @@ impl UiBridge {
|
||||
})
|
||||
}
|
||||
|
||||
/// 切换当前 Presentation 上下文;不会创建新窗口或复制 VM。
|
||||
pub fn select_window(&self, id: u64) -> Result<()> {
|
||||
let mut state = self
|
||||
.session
|
||||
@@ -937,6 +989,7 @@ impl UiBridge {
|
||||
state.current = id;
|
||||
Ok(())
|
||||
}
|
||||
/// 从托管展示域撤销窗口,退役 Mount 并清理该窗口的私有对象关系。
|
||||
pub fn retire_window(&self, vm: &mut Vm, id: u64) -> Result<()> {
|
||||
if id == crate::window::MAIN_WINDOW {
|
||||
bail!("the primary shell is closed by the OS window control");
|
||||
@@ -964,6 +1017,7 @@ impl UiBridge {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// 收尾已经关闭的展示资源,避免它们参与下一次窗口遍历。
|
||||
pub fn finish_closed(&self, vm: &mut Vm) -> Result<()> {
|
||||
let mut state = self
|
||||
.session
|
||||
@@ -988,6 +1042,7 @@ impl UiBridge {
|
||||
state.current = crate::window::MAIN_WINDOW;
|
||||
Ok(())
|
||||
}
|
||||
/// 从各托管窗口收集待发布命令;原生执行时还需校验 session。
|
||||
pub fn take_window_commands(&self, vm: &Vm) -> Result<Vec<crate::window::Command>> {
|
||||
let mut state = self
|
||||
.session
|
||||
@@ -1002,6 +1057,7 @@ impl UiBridge {
|
||||
Ok(commands)
|
||||
}
|
||||
|
||||
/// 校验并更新所属窗口的逻辑尺寸输入;尺寸不变时不制造新布局,改变时标记需要刷新。
|
||||
pub fn set_viewport(&self, vm: &mut Vm, viewport: Option<crate::layout::Size>) -> Result<bool> {
|
||||
if let Some(size) = viewport
|
||||
&& (!size.width.is_finite()
|
||||
@@ -1037,6 +1093,7 @@ impl UiBridge {
|
||||
Ok(true)
|
||||
}
|
||||
|
||||
/// 将 ui 入口与兼容名称安装到本次程序的全局字典,保持所有调用处在同一个 VM 域。
|
||||
pub fn install_globals(&self, vm: &mut Vm, globals: ObjectRef) -> Result<()> {
|
||||
vm.dict_set(globals, Value::Text("ui".into()), Value::Object(self.ui))?;
|
||||
// Compatibility spelling used by the original module examples.
|
||||
@@ -1051,6 +1108,7 @@ impl UiBridge {
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
/// 检查当前会话是否已经安排或拥有可展示页面。
|
||||
pub fn has_page(&self) -> Result<bool> {
|
||||
Ok(self
|
||||
.session
|
||||
@@ -1060,6 +1118,7 @@ impl UiBridge {
|
||||
.values()
|
||||
.any(|view| view.pending.flatten().is_some() || view.active.is_some()))
|
||||
}
|
||||
/// 验证标签拖放仍指向有效页面和窗口关系,避免旧拖动操作跨域生效。
|
||||
pub fn accepts_tab_drop(&self, vm: &Vm, input: &crate::events::Input) -> bool {
|
||||
let Some(target) = &input.tab_drop else {
|
||||
return true;
|
||||
@@ -1097,12 +1156,14 @@ impl UiBridge {
|
||||
}
|
||||
true
|
||||
}
|
||||
/// 通过展示协议打开源值,必要时创建或选择承载它的页面。
|
||||
pub fn open_value(&self, vm: &mut Vm, value: &Value) -> Result<()> {
|
||||
let function = object(Some(&vm.get_attr(self.ui, "open")?))?;
|
||||
let page = vm.call(function, std::slice::from_ref(value))?;
|
||||
vm.release_value(page)?;
|
||||
Ok(())
|
||||
}
|
||||
/// 处理页面激活、关闭、移动和拆分等标签操作,保持窗口所有权与展示状态一致。
|
||||
fn dispatch_tab(&self, vm: &mut Vm, input: &crate::events::Input) -> Result<()> {
|
||||
let page = {
|
||||
let state = self
|
||||
@@ -1214,6 +1275,7 @@ impl UiBridge {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// 在所属窗口的展示上下文中处理输入,区分页面管理、滚动、焦点、相机与普通事件。
|
||||
pub fn dispatch(&self, vm: &mut Vm, input: &crate::events::Input) -> Result<()> {
|
||||
input
|
||||
.validate()
|
||||
@@ -1419,6 +1481,7 @@ impl UiBridge {
|
||||
vm.release(mount)?;
|
||||
result
|
||||
}
|
||||
/// 整理不再有效的弱索引与展示根,并配合 VM 回收,避免派生缓存延长业务对象生命周期。
|
||||
pub fn reclaim(&self, vm: &mut Vm, _roots: &mut Vec<ObjectRef>) -> Result<()> {
|
||||
vm.collect_cycles();
|
||||
let mut state = self
|
||||
@@ -1438,6 +1501,7 @@ impl UiBridge {
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
/// 丢弃未成功发布的展示请求,恢复后续输入可以使用的会话状态。
|
||||
pub fn discard_pending(&self, vm: &mut Vm) -> Result<()> {
|
||||
let mut state = self
|
||||
.session
|
||||
@@ -1488,6 +1552,7 @@ impl UiBridge {
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
/// 重新评估已失效的属性绑定,并把结果计入会话统计。
|
||||
pub fn refresh_bindings(&self, vm: &mut Vm) -> Result<()> {
|
||||
let (nodes, desktops) = {
|
||||
let state = self
|
||||
@@ -1504,6 +1569,7 @@ impl UiBridge {
|
||||
state.binding_evaluations = state.binding_evaluations.saturating_add(evaluated);
|
||||
Ok(())
|
||||
}
|
||||
/// 排空一次 VM 变化记录并通知各窗口,提取活动页面快照,判断本次是否需要布局与发布。
|
||||
pub fn prepare_frame(&self, vm: &mut Vm) -> Result<Option<Option<Arc<UiNode>>>> {
|
||||
let changes = vm.take_changes();
|
||||
let mut state = self
|
||||
@@ -1548,6 +1614,7 @@ impl UiBridge {
|
||||
}
|
||||
Ok(changed.then_some(root))
|
||||
}
|
||||
/// 提交已经完成的出现几何与快照,并处理展示生命周期;不把挂起或失败的布局当成已发布帧。
|
||||
pub fn commit_frame(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -1603,6 +1670,7 @@ impl UiBridge {
|
||||
result
|
||||
}
|
||||
|
||||
/// 在已完成的几何上启动绘制协议,保留绘制任务所需的宿主上下文。
|
||||
pub fn begin_paint_frame(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -1633,6 +1701,7 @@ impl UiBridge {
|
||||
self.accept_paint_progress(progress)
|
||||
}
|
||||
|
||||
/// 恢复同一次源绘制调用,把完成的 Draft 交回发布流程。
|
||||
pub fn resume_paint_frame(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -1642,6 +1711,7 @@ impl UiBridge {
|
||||
self.accept_paint_progress(progress)
|
||||
}
|
||||
|
||||
/// 区分挂起与完成的绘制进度;完成时保存真实读取依赖并接回发布流程。
|
||||
fn accept_paint_progress(
|
||||
&self,
|
||||
progress: crate::source_paint::Progress,
|
||||
@@ -1666,6 +1736,7 @@ impl UiBridge {
|
||||
Ok(progress)
|
||||
}
|
||||
|
||||
/// 取消尚未完成的源绘制,释放其续体和未发布上下文。
|
||||
pub fn cancel_paint_frame(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -1684,6 +1755,7 @@ impl UiBridge {
|
||||
invalidated
|
||||
}
|
||||
|
||||
/// 为目标快照建立 Mount、检查点和布局上下文,再启动可挂起的只读布局求解。
|
||||
pub fn begin_layout_frame(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -1806,6 +1878,7 @@ impl UiBridge {
|
||||
self.accept_layout_progress(vm, context, progress)
|
||||
}
|
||||
|
||||
/// 记录本次刷新主动让出 worker 的次数,用于诊断分片执行。
|
||||
pub fn note_refresh_yield(&self) -> Result<()> {
|
||||
let mut state = self
|
||||
.session
|
||||
@@ -1815,6 +1888,7 @@ impl UiBridge {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// 记录视口目标替换导致的刷新重启,便于区分正常挂起与取消重试。
|
||||
pub fn note_refresh_restart(
|
||||
&self,
|
||||
cancelled_layout: bool,
|
||||
@@ -1834,6 +1908,7 @@ impl UiBridge {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// 撤销未完成布局所保留的窗口、挂载与生命周期上下文。
|
||||
fn discard_layout_context(&self, vm: &mut Vm, context: LayoutContext) -> Result<()> {
|
||||
let LayoutContext {
|
||||
surface: _,
|
||||
@@ -1866,6 +1941,7 @@ impl UiBridge {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// 取消源布局续体并清理对应上下文,保持已发布帧可用。
|
||||
pub fn cancel_layout_frame(&self, vm: &mut Vm, pending: PendingLayout) -> Result<()> {
|
||||
let PendingLayout { work, context } = pending;
|
||||
let cancelled = work.cancel(vm);
|
||||
@@ -1874,10 +1950,12 @@ impl UiBridge {
|
||||
restored
|
||||
}
|
||||
|
||||
/// 关闭失败布局的挂起工作并恢复检查点;供错误或候选撤销路径使用。
|
||||
pub fn abort_layout_frame(&self, vm: &mut Vm, pending: PendingLayout) -> Result<()> {
|
||||
self.cancel_layout_frame(vm, pending)
|
||||
}
|
||||
|
||||
/// 继续同一次尚未发布的布局任务;完成时沿原上下文收尾,不能新建一轮来重放副作用。
|
||||
pub fn resume_layout_frame(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -1895,6 +1973,7 @@ impl UiBridge {
|
||||
self.accept_layout_progress(vm, context, progress)
|
||||
}
|
||||
|
||||
/// 接收布局的 Pending/Complete 结果;保留上下文或执行最终投影和提交。
|
||||
fn accept_layout_progress(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -1918,6 +1997,7 @@ impl UiBridge {
|
||||
}
|
||||
}
|
||||
|
||||
/// 依次投影滚动/视口、补页面元数据、保存读取版本、提交 Mount,并处理延后的生命周期调用。
|
||||
fn finish_layout_frame(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -2018,6 +2098,7 @@ impl UiBridge {
|
||||
Ok(frame)
|
||||
}
|
||||
|
||||
/// 读取当前源程序已经选择的展示内容,为编译入口生成最终文档提供根。
|
||||
pub fn rendered(&self, vm: &Vm) -> Result<Option<Arc<UiNode>>> {
|
||||
let state = self
|
||||
.session
|
||||
@@ -2032,6 +2113,7 @@ impl UiBridge {
|
||||
}
|
||||
}
|
||||
|
||||
/// 从会话的类型注册表取得指定类型,再给原生分配的对象附加托管类型身份。
|
||||
fn attach_named_type(
|
||||
cx: &mut NativeContext<'_>,
|
||||
object: ObjectRef,
|
||||
@@ -2045,6 +2127,7 @@ fn attach_named_type(
|
||||
attach_desktop_type(cx, object, name, desktop)
|
||||
}
|
||||
|
||||
/// 按给定 desktop 查找类型并附加,支持不同窗口使用自己的展示上下文。
|
||||
pub fn attach_desktop_type(
|
||||
cx: &mut NativeContext<'_>,
|
||||
instance: ObjectRef,
|
||||
@@ -2055,6 +2138,7 @@ pub fn attach_desktop_type(
|
||||
cx.attach_type(instance, definition)
|
||||
}
|
||||
|
||||
/// 读取 desktop 的托管类型注册表;缺失或类型错误时返回 VM 错误。
|
||||
pub(crate) fn desktop_type(
|
||||
store: &endor_core::ObjectStore,
|
||||
name: &str,
|
||||
@@ -2064,6 +2148,7 @@ pub(crate) fn desktop_type(
|
||||
object(store.dict_get(types, &Value::Text(name.into()))?.as_ref())
|
||||
}
|
||||
|
||||
/// 将当前托管或可变状态提取为后续阶段使用的派生表示。
|
||||
pub fn snapshot(vm: &Vm, value: &Value) -> Result<Arc<UiNode>> {
|
||||
let Value::Object(root) = value else {
|
||||
bail!("main must return a Block");
|
||||
|
||||
@@ -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