Struct UndoRedo

pub struct UndoRedo { /* private fields */ }

Expand description

Godot class UndoRedo.

Inherits Object.

Related symbols:

undo_redo: sidecar module with related enum/flag types
IUndoRedo: virtual methods
SignalsOfUndoRedo: signal collection

§Construction

This class is manually managed. You can create a new instance using UndoRedo::new_alloc().

Do not forget to call free() or hand over ownership to Godot.

§Godot docs

UndoRedo works by registering methods and property changes inside “actions”. You can create an action, then provide ways to do and undo this action using function calls and property changes, then commit the action.

When an action is committed, all of the do_* methods will run. If the undo method is used, the undo_* methods will run. If the redo method is used, once again, all of the do_* methods will run.

Here’s an example on how to add an action:

var undo_redo = UndoRedo.new()

func do_something():
	pass # Put your code here.

func undo_something():
	pass # Put here the code that reverts what's done by "do_something()".

func _on_my_button_pressed():
	var node = get_node("MyNode2D")
	undo_redo.create_action("Move the node")
	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()

Before calling any of the add_(un)do_* methods, you need to first call create_action. Afterwards you need to call commit_action.

If you don’t need to register a method, you can leave add_do_method and add_undo_method out; the same goes for properties. You can also register more than one method/property.

If you are making an EditorPlugin and want to integrate into the editor’s undo history, use EditorUndoRedoManager instead.

If you are registering multiple properties/method which depend on one another, be aware that by default undo operation are called in the same order they have been added. Therefore instead of grouping do operation with their undo operations it is better to group do on one side and undo on the other as shown below.

undo_redo.create_action("Add object")

# 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()

Implementations§

§

impl UndoRedo

pub fn create_action(&mut self, name: impl AsArg<GString>)

To set the default parameters, use create_action_ex and its builder methods. See the book for detailed usage instructions. Create a new action. After this is called, do all your calls to add_do_method, add_undo_method, add_do_property, and add_undo_property, then commit the action with commit_action.

The way actions are merged is dictated by merge_mode.

The way undo operation are ordered in actions is dictated by backward_undo_ops. When backward_undo_ops is false undo option are ordered in the same order they were added. Which means the first operation to be added will be the first to be undone.

pub fn create_action_ex<'ex>( &'ex mut self, name: impl AsArg<GString> + 'ex, ) -> ExCreateAction<'ex>

Create a new action. After this is called, do all your calls to add_do_method, add_undo_method, add_do_property, and add_undo_property, then commit the action with commit_action.

The way actions are merged is dictated by merge_mode.

The way undo operation are ordered in actions is dictated by backward_undo_ops. When backward_undo_ops is false undo option are ordered in the same order they were added. Which means the first operation to be added will be the first to be undone.

pub fn commit_action(&mut self)

To set the default parameters, use commit_action_ex and its builder methods. See the book for detailed usage instructions. Commit the action. If execute is true (which it is by default), all “do” methods/properties are called/set when this function is called.

pub fn commit_action_ex<'ex>(&'ex mut self) -> ExCommitAction<'ex>

Commit the action. If execute is true (which it is by default), all “do” methods/properties are called/set when this function is called.

pub fn is_committing_action(&self) -> bool

Returns true if the UndoRedo is currently committing the action, i.e. running its “do” method or property change (see commit_action).

pub fn add_do_method(&mut self, callable: &Callable)

Register a Callable that will be called when the action is committed.

pub fn add_undo_method(&mut self, callable: &Callable)

Register a Callable that will be called when the action is undone.

pub fn add_do_property( &mut self, object: impl AsArg<Option<Gd<Object>>>, property: impl AsArg<StringName>, value: &Variant, )

Register a property that would change its value to value when the action is committed.

pub fn add_undo_property( &mut self, object: impl AsArg<Option<Gd<Object>>>, property: impl AsArg<StringName>, value: &Variant, )

Register a property that would change its value to value when the action is undone.

pub fn add_do_reference(&mut self, object: impl AsArg<Option<Gd<Object>>>)

Register a reference to an object that will be erased if the “do” history is deleted. This is useful for objects added by the “do” action and removed by the “undo” action.

When the “do” history is deleted, if the object is a RefCounted, it will be unreferenced. Otherwise, it will be freed. Do not use for resources.

var node = Node2D.new()
undo_redo.create_action("Add node")
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()

pub fn add_undo_reference(&mut self, object: impl AsArg<Option<Gd<Object>>>)

Register a reference to an object that will be erased if the “undo” history is deleted. This is useful for objects added by the “undo” action and removed by the “do” action.

When the “undo” history is deleted, if the object is a RefCounted, it will be unreferenced. Otherwise, it will be freed. Do not use for resources.

var node = $Node2D
undo_redo.create_action("Remove node")
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()

pub fn start_force_keep_in_merge_ends(&mut self)

Marks the next “do” and “undo” operations to be processed even if the action gets merged with another in the MergeMode::ENDS mode. Return to normal operation using end_force_keep_in_merge_ends.

pub fn end_force_keep_in_merge_ends(&mut self)

Stops marking operations as to be processed even if the action gets merged with another in the MergeMode::ENDS mode. See start_force_keep_in_merge_ends.

pub fn get_history_count(&self) -> i32

Returns how many elements are in the history.

pub fn get_current_action(&self) -> i32

Gets the index of the current action.

pub fn get_action_name(&self, id: i32) -> GString

Gets the action name from its index.

pub fn clear_history(&mut self)

To set the default parameters, use clear_history_ex and its builder methods. See the book for detailed usage instructions. Clear the undo/redo history and associated references.

Passing false to increase_version will prevent the version number from increasing when the history is cleared.

pub fn clear_history_ex<'ex>(&'ex mut self) -> ExClearHistory<'ex>

Clear the undo/redo history and associated references.

Passing false to increase_version will prevent the version number from increasing when the history is cleared.

pub fn get_current_action_name(&self) -> GString

Gets the name of the current action, equivalent to get_action_name(get_current_action()).

pub fn has_undo(&self) -> bool

Returns true if an “undo” action is available.

pub fn has_redo(&self) -> bool

Returns true if a “redo” action is available.

pub fn get_version(&self) -> u64

Gets the version. Every time a new action is committed, the UndoRedo’s version number is increased automatically.

This is useful mostly to check if something changed from a saved version.

pub fn set_max_steps(&mut self, max_steps: i32)

pub fn get_max_steps(&self) -> i32

pub fn redo(&mut self) -> bool

Redo the last action.

pub fn undo(&mut self) -> bool

Undo the last action.

Methods from Deref<Target = Object>§

pub fn get_script(&self) -> Option<Gd<Script>>

pub fn set_script(&mut self, script: impl AsArg<Option<Gd<Script>>>)

pub fn connect( &mut self, signal: impl AsArg<StringName>, callable: &Callable, ) -> Error

pub fn connect_flags( &mut self, signal: impl AsArg<StringName>, callable: &Callable, flags: ConnectFlags, ) -> Error

pub fn get_class(&self) -> GString

Returns the object’s built-in class name, as a String. See also is_class.

Note: This method ignores class_name declarations. If this object’s script has defined a class_name, the base, built-in class name is returned instead.

pub fn is_class(&self, class: impl AsArg<GString>) -> bool

Returns true if the object inherits from the given class. See also get_class.

var sprite2d = Sprite2D.new()
sprite2d.is_class("Sprite2D") # Returns true
sprite2d.is_class("Node")     # Returns true
sprite2d.is_class("Node3D")   # Returns false

Note: This method ignores class_name declarations in the object’s script.

pub fn set(&mut self, property: impl AsArg<StringName>, value: &Variant)

Assigns value to the given property. If the property does not exist or the given value’s type doesn’t match, nothing happens.

var node = Node2D.new()
node.set("global_scale", Vector2(8, 2.5))
print(node.global_scale) # Prints (8.0, 2.5)

Note: In C#, property must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

pub fn get(&self, property: impl AsArg<StringName>) -> Variant

Returns the Variant value of the given property. If the property does not exist, this method returns null.

var node = Node2D.new()
node.rotation = 1.5
var a = node.get("rotation") # a is 1.5

Note: In C#, property must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

pub fn set_indexed( &mut self, property_path: impl AsArg<NodePath>, value: &Variant, )

Assigns a new value to the property identified by the property_path. The path should be a NodePath relative to this object, and can use the colon character (:) to access nested properties.

var node = Node2D.new()
node.set_indexed("position", Vector2(42, 0))
node.set_indexed("position:y", -10)
print(node.position) # Prints (42.0, -10.0)

Note: In C#, property_path must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

pub fn get_indexed(&self, property_path: impl AsArg<NodePath>) -> Variant

Gets the object’s property indexed by the given property_path. The path should be a NodePath relative to the current object and can use the colon character (:) to access nested properties.

Examples: "position:x" or "material:next_pass:blend_mode".

var node = Node2D.new()
node.position = Vector2(5, -10)
var a = node.get_indexed("position")   # a is Vector2(5, -10)
var b = node.get_indexed("position:y") # b is -10

Note: In C#, property_path must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

Note: This method does not support actual paths to nodes in the SceneTree, only sub-property paths. In the context of nodes, use get_node_and_resource instead.

pub fn get_property_list(&self) -> Array<Dictionary<Variant, Variant>>

Returns the object’s property list as an Array of dictionaries. Each Dictionary contains the following entries:

name is the property’s name, as a String;
class_name is an empty StringName, unless the property is VariantType::OBJECT and it inherits from a class;
type is the property’s type, as an int (see [enum Variant.Type]);
hint is how the property is meant to be edited (see [enum PropertyHint]);
hint_string depends on the hint (see [enum PropertyHint]);
usage is a combination of [enum PropertyUsageFlags].

Note: In GDScript, all class members are treated as properties. In C# and GDExtension, it may be necessary to explicitly mark class members as Godot properties using decorators or attributes.

pub fn get_method_list(&self) -> Array<Dictionary<Variant, Variant>>

Returns this object’s methods and their signatures as an Array of dictionaries. Each Dictionary contains the following entries:

name is the name of the method, as a String;
args is an Array of dictionaries representing the arguments;
default_args is the default arguments as an Array of variants;
flags is a combination of [enum MethodFlags];
id is the method’s internal identifier int;
return is the returned value, as a Dictionary;

Note: The dictionaries of args and return are formatted identically to the results of get_property_list, although not all entries are used.

pub fn property_can_revert(&self, property: impl AsArg<StringName>) -> bool

Returns true if the given property has a custom default value. Use property_get_revert to get the property’s default value.

Note: This method is used by the Inspector dock to display a revert icon. The object must implement [method _property_can_revert] to customize the default value. If [method _property_can_revert] is not implemented, this method returns false.

pub fn property_get_revert(&self, property: impl AsArg<StringName>) -> Variant

Returns the custom default value of the given property. Use property_can_revert to check if the property has a custom default value.

Note: This method is used by the Inspector dock to display a revert icon. The object must implement [method _property_get_revert] to customize the default value. If [method _property_get_revert] is not implemented, this method returns null.

pub fn set_meta(&mut self, name: impl AsArg<StringName>, value: &Variant)

Adds or changes the entry name inside the object’s metadata. The metadata value can be any Variant, although some types cannot be serialized correctly.

If value is null, the entry is removed. This is the equivalent of using remove_meta. See also has_meta and get_meta.