UndoRedo
继承: Object
为实现撤销和重做操作提供高阶接口。
描述
UndoRedo 的原理是在“动作”中注册方法和属性的变化。你可以创建一个动作,然后提供执行(do)和撤销(undo)这个动作需要进行的函数调用和属性更改,然后提交该动作。
动作提交后就会执行所有 do_*
方法。如果使用 undo 方法,那么就会执行 undo_*
方法。如果使用 redo 方法,那么就会再次执行所有 do_*
方法。
以下是添加动作的示例:
GDScriptC#
var undo_redo = UndoRedo.new()
func do_something():
pass # 在此处编写你的代码。
func undo_something():
pass # 在此处编写恢复“do_something()”里所做事情的代码。
func _on_my_button_pressed():
var node = get_node("MyNode2D")
undo_redo.create_action("移动节点")
undo_redo.add_do_method(do_something)
undo_redo.add_undo_method(undo_something)
undo_redo.add_do_property(node, "position", Vector2(100,100))
undo_redo.add_undo_property(node, "position", node.position)
undo_redo.commit_action()
private UndoRedo _undoRedo;
public override void _Ready()
{
_undoRedo = new UndoRedo();
}
public void DoSomething()
{
// 在此处编写你的代码。
}
public void UndoSomething()
{
// 在此处编写恢复“DoSomething()”里所做事情的代码。
}
private void OnMyButtonPressed()
{
var node = GetNode<Node2D>("MyNode2D");
_undoRedo.CreateAction("移动节点");
_undoRedo.AddDoMethod(new Callable(this, MethodName.DoSomething));
_undoRedo.AddUndoMethod(new Callable(this, MethodName.UndoSomething));
_undoRedo.AddDoProperty(node, "position", new Vector2(100, 100));
_undoRedo.AddUndoProperty(node, "position", node.Position);
_undoRedo.CommitAction();
}
调用 add_(un)do_*
方法之前,你需要先调用 create_action。调用之后则需要调用 commit_action。
如果你不需要注册方法,则可以将 add_do_method 和 add_undo_method 省去;属性同理。你也可以注册多个方法/属性。
如果你要制作 EditorPlugin,希望集成编辑器的撤销历史,请改用 EditorUndoRedoManager。
如果你所注册的不同属性/方法之间有相互依赖,请注意默认情况下撤销操作的调用顺序和添加顺序是一致的。因此请不要将 do 操作和 undo 操作写在一起,最好还是和下面一样 do 和 do 一起写,undo 和 undo 一起写。
GDScriptC#
undo_redo.create_action("添加对象")
# DO
undo_redo.add_do_method(_create_object)
undo_redo.add_do_method(_add_object_to_singleton)
# UNDO
undo_redo.add_undo_method(_remove_object_from_singleton)
undo_redo.add_undo_method(_destroy_that_object)
undo_redo.commit_action()
_undo_redo.CreateAction("添加对象");
// DO
_undo_redo.AddDoMethod(new Callable(this, MethodName.CreateObject));
_undo_redo.AddDoMethod(new Callable(this, MethodName.AddObjectToSingleton));
// UNDO
_undo_redo.AddUndoMethod(new Callable(this, MethodName.RemoveObjectFromSingleton));
_undo_redo.AddUndoMethod(new Callable(this, MethodName.DestroyThatObject));
_undo_redo.CommitAction();
方法
void | add_do_method ( Callable callable ) |
void | add_do_property ( Object object, StringName property, Variant value ) |
void | add_do_reference ( Object object ) |
void | add_undo_method ( Callable callable ) |
void | add_undo_property ( Object object, StringName property, Variant value ) |
void | add_undo_reference ( Object object ) |
void | clear_history ( bool increase_version=true ) |
void | commit_action ( bool execute=true ) |
void | create_action ( String name, MergeMode merge_mode=0, bool backward_undo_ops=false ) |
void | |
get_action_name ( int id ) | |
get_current_action_name ( ) const | |
get_version ( ) const | |
has_redo ( ) const | |
has_undo ( ) const | |
is_committing_action ( ) const | |
redo ( ) | |
void | |
undo ( ) |
信号
version_changed ( )
枚举
enum MergeMode:
MergeMode MERGE_DISABLE = 0
使“do”/“undo”操作保持在单独的动作中。
MergeMode MERGE_ENDS = 1
使得动作的“撤消”操作来自创建的第一个动作,“执行”操作来自最后一个具有相同名称的后续动作。
MergeMode MERGE_ALL = 2
使具有相同名称的后续动作合并为一个。
方法说明
void add_do_method ( Callable callable )
注册 Callable,会在提交动作时调用。
void add_do_property ( Object object, StringName property, Variant value )
注册 property
,会在提交动作时将其值更改为 value
。
void add_do_reference ( Object object )
为“do”(执行)注册引用,丢弃该“do”历史时会擦除该引用。主要可用于“do”调用新建的节点。请勿用于资源。
var node = Node2D.new()
undo_redo.create_action("添加节点")
undo_redo.add_do_method(add_child.bind(node))
undo_redo.add_do_reference(node)
undo_redo.add_undo_method(remove_child.bind(node))
undo_redo.commit_action()
void add_undo_method ( Callable callable )
注册 Callable,会在撤销动作时调用。
void add_undo_property ( Object object, StringName property, Variant value )
注册 property
,会在撤销动作时将其值更改为 value
。
void add_undo_reference ( Object object )
为“undo”(撤销)注册引用,丢弃该“undo”历史时会擦除该引用。主要可用于“do”调用移除的节点(不是“undo”调用)。
var node = $Node2D
undo_redo.create_action("移除节点")
undo_redo.add_do_method(remove_child.bind(node))
undo_redo.add_undo_method(add_child.bind(node))
undo_redo.add_undo_reference(node)
undo_redo.commit_action()
void clear_history ( bool increase_version=true )
清除撤销/重做历史和相关的引用。
将 false
传递给 increase_version
将防止在清除历史记录时增加版本号。
void commit_action ( bool execute=true )
提交动作。如果 execute
为 true
(默认情况),则会在调用此函数时调用/设置所有“执行(do)”方法/属性。
void create_action ( String name, MergeMode merge_mode=0, bool backward_undo_ops=false )
创建一个新的动作。调用后,请执行所有你需要的 add_do_method、add_undo_method、add_do_property 和 add_undo_property 调用,然后再用 commit_action 提交这个动作。
动作的合并方式由 merge_mode
决定。详见 MergeMode。
动作中撤销操作的顺序由 backward_undo_ops
决定。backward_undo_ops
为 false
时,撤销选项的顺序和添加顺序一致。也就是说,先添加的操作会先撤销。
void end_force_keep_in_merge_ends ( )
停止将操作标记为要处理,即使该动作在 MERGE_ENDS 模式下与另一个动作合并。请参阅 start_force_keep_in_merge_ends。
String get_action_name ( int id )
根据索引获取动作名称。
int get_current_action ( )
获取当前动作的索引。
String get_current_action_name ( ) const
获取当前动作的名称,等价于 get_action_name(get_current_action())
。
int get_history_count ( )
返回历史中有多少元素。
int get_version ( ) const
获取版本。每次提交一个新的操作,UndoRedo 的版本号都会自动增加。
这主要用于检查保存的版本是否发生了更改。
bool has_redo ( ) const
有“重做”动作可用时返回 true
。
bool has_undo ( ) const
有“撤销”动作可用时返回 true
。
bool is_committing_action ( ) const
如果 UndoRedo 当前正在提交动作,即运行其“do”的方法或属性变化,则返回 true
(请参阅 commit_action)。
bool redo ( )
重做上一个动作。
void start_force_keep_in_merge_ends ( )
标记要处理的下一个“执行”和“撤消”操作,即使该动作在 MERGE_ENDS 模式下与另一个动作合并。使用 end_force_keep_in_merge_ends 返回到正常操作。
bool undo ( )
撤销上一个动作。
© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7
.
Built with Sphinx using a theme provided by Read the Docs.