设计器写回
设计器是 .dui 的前端——一次编辑写进哪一行、手写的文件如何保持不动,以及它拒绝哪些编辑(DUI7xxx)。
设计器写回什么
设计器是该文件的前端:在那里做的改动就是对文本的改动,写进保存该值的那一行——或者写进该节点其他行之后的新行——其余内容逐字节保持原样。
值。 数字、字符串、元组、颜色、枚举和资产引用都写成语言能读取的字面值。列表或集合写成 [a, b],映射写成 { key: value },整个容器替换它所在的那一行;只是以另一种顺序返回的集合或映射不算改动,确有改动的则保留文件中的顺序,新条目加在后面。元素如果是没有简写形式的结构体,则有两种写法。指明了主字段(DreamGUI_PrimaryField;目前是环状菜单的项)的结构体是一个字段映射:Items = [{ "Lamp", Tag: Lamp }, { "Door", Tag: Door, bEnabled: false }],主字段在最前且不带其键,之后只写与结构体默认值不同的字段,其文本字段各自获得本地化键(Items.Label)。其他任何结构体——图层样式的投影、一项调整——写成与结构体默认值不同的那些字段的带引号文本,和构建器读取的一样:Style.DropShadows = ["(Angle=45.000000,Distance=8.000000)"]。之所以保持这种形式,是因为像线性颜色这样的字段在映射中会通过十六进制代码被量化。指向本层级另一个控件的引用(显式导航目标、开关的组)写成该节点的裸 id;指向另一个文件组件内部的引用在这里没有 id,会被拒绝。
一次旋转——通过 2D 视图的旋转手柄、3D 视图的 gizmo 或细节面板完成——会写为欧拉角 RelativeRotationEuler = (0, 0, 30):pitch、yaw 和 roll,单位为度;画布平面内的旋转就是 roll,正值表示顺时针。资产所保存的四元数没有拼写形式,也永远不会被写出。
节点从样式的 + Component 行取到的值,写成节点上的覆盖行:节点自己的一条 + Component { … },里面是改过的值。样式是共享的,保持不动。
@fill N 换了权重就替换数字;裸的 @fill 被赋予另一条 SizeRule 时变为 @slot SizeRule = …;@fill 2 被赋予另一条规则时变成它代表的两行:@slot SizeRule = … 和 @slot FillWeight = 2。
标签。 Tags 写成该节点的 @tag 行。设计器移除的名称会从其所在行中删除,留下的空行则被去掉;它添加的名称会并入最后一行保留名称的行,若没有这样的行,则在节点的其他行之后新增一行 @tag。写了 Tags = [...] 的节点保留该行并重写它。同时以两种方式写标签的节点会被拒绝(DUI7004),在已有标签行的节点上,@tag 行无法容纳的名称(含空格或以数字开头)也会被拒绝。在没有任何标签行的节点上,这样的名称写成一行 Tags = [...]。
@slot Size。 如果一次编辑后槽位的最小和最大期望尺寸仍然相等,则重写简写形式的值。若使二者不同,则把该行重写为 @slot MinDesiredSize = … 和 @slot MaxDesiredSize = …——在 @slot { } 块内则是该块的两行,当块位于一行时二者并排。既未写这两者、又被赋予同一个值的节点会得到一行 @slot Size,这正是蓝图转换器为这类槽位所写的内容。
多个样式。 对节点值的编辑永远不会重写节点的 : A : B。样式赋予节点的值按构建器应用它们的顺序获取,发生改动的值写成节点自己的一行,放在最后。
结构。 在设计器中添加的控件会按该文件会使用的类型写出:当该类在此处有 use … as 别名时使用该别名,对于排布子节点的普通控件则使用容器类型(VerticalBox Column)。拖入组件实例某个具名槽位的控件会写进该槽位的填充,slot Detail { … },当实例没有该槽位的填充时会先写出它。删除控件会删掉它的整个块;移动控件会把它的文本提起来,放回它现在所在的兄弟之前;重命名写成新 id 加 (was: OldId),下次编译会把旧名字拥有的变量、绑定、动画路径和本地化 key 带过去。在设计器中重命名的无名节点会获得其第一个 id,写在类型之后。行为就是增删和移动 + 行;换面板或视觉类会改写节点的类型或它的 + 行,新类没有的属性行会被删掉。
rows 表格的一行就是一行文本:删除就删掉这行,移动就把这行提到同一表格的另一行之前,复制就复制这行(副本的 key 会被加编号,直到作者给它起自己的)。
语句。 Bind 控件的绑定写成 Property <- Function(),属性已有自己的行就替换那一行;Remove Binding 删掉这行,Unbind and Set to This Value 在原位写 Property = value。两路绑定写成 Value <-> Variable(或 viewmodel 成员,Value <-> Settings.Volume),只在通过 OnValueChangedBP 报告值的控件上提供。来自 Events 行的路由写成 Event -> Handler:写在节点的行上,或者对于节点自身写成 + Component 块的行为,写进该节点自己的块中。这些语句直接写进文档,每条一行,在这次操作的事务里。
动画。 在动画编辑器里对 timeline 块动画的编辑会写回块里:关键帧的时间和值、两个关键帧之间的 ease、事件关键帧、duration,加一条轨道就写一行、删一条就删一行。关键帧没变的轨道,那一行逐字节不动;注释和 loop 行保持原样。
会拒绝的,在动手之前说明原因——有几种东西没有可写入的行,设计器会直接说明(DUI7004),而不是凭空造一行:
- 由
if显示或隐藏的控件的可见性——改条件,或者把该控件移出分支——以及写在前端生成(而非读到)的行上的绑定或路由; - 删除
for或each的模板或把它移出循环:没有东西可重复的循环无法构建; rows表格上:给一行改名、给它加+块、把它移出表格,或者把节点放在表格旁边(那个位置会在表格内部);- 对某节点上
Tags的改动,该节点同时将其写成@tag行和Tags = [...]行;或者向已有标签行的节点添加@tag行无法容纳的名称; - 类型或内容没有写法的值(DUI7003,在有写法的类型里目前只有非有限浮点数);
- 动画编辑器里带自定义切线或阶梯插值的关键帧——写
timeline Name external,把动画永久交给 Sequencer。
如果源文件为只读或写入失败,文档会在内存中保留编辑后的文本。之后的 flush 会重试该写入,即使没有任何值发生改变。编译也会重试,并在仍无法写入时报告 DUI6023;当前层级和编辑内容会保留。请签出该文件或解决写入失败问题,然后再次编译。
从设计器值回到文本
FDreamUITextWriteBack 将设计器编辑转换为 .dui 改动。其核心规则是比较值,而不是源文本的拼写。FDreamUITextPatcher 编辑文本片段;如果把设计器可能碰过的每个属性都交给它,那么只要打印器的格式与作者的写法不同,未改变的值也会被重写。例如,(400,240) 和 (400, 240) 描述的是同一个值。
因此,一次 flush 会询问:重建当前文本是否会产出实时树所持有的值。它会用编译器自身的 FDreamUITextBuilder 从该文本构建第二棵树,然后比较值。它不会为写回另行维护一套对语言的解释。
一次 flush 就是一步撤销,或者在没有变化时不算一步。空操作不会调用 SetContent,也不会创建空事务。撤销会把树标记为在下一个 tick 重新生成:该通知是在 FTransaction::Apply 内部到达的,当时它仍在恢复对象,因此同一事务中的其他控件可能尚未恢复它们的值。
文本住在哪里:UDreamUIDocument
对于以文本为后端的控件,文本是唯一真相,设计器是它的图形前端。UDreamUIDocument,一个位于 DreamGUIEditor 中的 UCLASS(Transient) UObject,保存一个 .dui 文件的完整文本,以便 Unreal 的事务系统能够撤销它。
UObject 之所以重要,是因为撤销恢复的是对象。如果文本位于事务之外,Ctrl+Z 可能恢复控件,却在文件中留下新值。随后一次重新编译、重新打开或下一次无关编辑都会从该文件重新生成树,并把本应撤销的改动带回来。
调用方必须遵守三条契约:
- 调用方拥有事务。
SetContent会调用Modify(),但它自己从不开启事务。它会报告缺少事务,而不是悄悄产生一次不可撤销的编辑。 - 内存是权威;磁盘可能滞后。 写入失败时,例如文件只读且尚未签出,会把编辑保留在内存中,报告失败,并在之后的 flush 中重试。
FlushToDisk从不清除只读位。 通过源代码控制签出该文件,而不是绕过源代码控制系统把它改成可写。
每个文件只有一个文档,而不是每个编辑器窗口一个。两个工具包为同一个文件持有各自独立的文档时,会有独立的文本和磁盘哈希:其中一个里的撤销在另一个看来可能像是外部编辑,导致这些窗口不断重新加载并覆盖彼此的状态。
FDreamUIDocumentRegistry 通过把规范化后的绝对路径用作键来防止这种情况。注册表持有弱引用;调用方通过 FDreamUIDocumentHandle 保留文档,这是一个只可移动、不可复制的有作用域句柄。文档 API 和这一所有权契约声明于 Source/DreamGUIEditor/Public/Text/DreamUIDocument.h。