UndoRedo

Inherits: Object

Helper to manage undo/redo operations in the editor or custom tools.

Description

Helper to manage undo/redo operations in the editor or custom tools. It works by registering methods and property changes inside “actions”.

Common behavior is to create an action, then add do/undo calls to functions or property changes, then committing the action.

Here’s an example on how to add an action to the Godot editor’s own UndoRedo, from a plugin:

var undo_redo = get_undo_redo() # Method of EditorPlugin.

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_MyButton_pressed():
    var node = get_node("MyNode2D")
    undo_redo.create_action("Move the node")
    undo_redo.add_do_method(self, "do_something")
    undo_redo.add_undo_method(self, "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()

create_action, add_do_method, add_undo_method, add_do_property, add_undo_property, and commit_action should be called one after the other, like in the example. Not doing so could lead to crashes.

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.

Methods

void add_do_method ( Object object, String method, … ) vararg
void add_do_property ( Object object, String property, Variant value )
void add_do_reference ( Object object )
void add_undo_method ( Object object, String method, … ) vararg
void add_undo_property ( Object object, String property, Variant value )
void add_undo_reference ( Object object )
void clear_history ( bool increase_version=true )
void commit_action ( )
void create_action ( String name, MergeMode merge_mode=0 )
String get_current_action_name ( ) const
int get_version ( ) const
bool has_redo ( )
bool has_undo ( )
bool is_commiting_action ( ) const
bool redo ( )
bool undo ( )

Signals

  • version_changed ( )

Called when undo or redo was called.

Enumerations

enum MergeMode:

  • MERGE_DISABLE = 0 — Makes “do”/”undo” operations stay in separate actions.
  • MERGE_ENDS = 1 — Makes so that the action’s “do” operation is from the first action created and the “undo” operation is from the last subsequent action with the same name.
  • MERGE_ALL = 2 — Makes subsequent actions with the same name be merged into one.

Method Descriptions

  • void add_do_method ( Object object, String method, … ) vararg

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

Register a property value change for “do”.

  • void add_do_reference ( Object object )

Register a reference for “do” that will be erased if the “do” history is lost. This is useful mostly for new nodes created for the “do” call. Do not use for resources.

  • void add_undo_method ( Object object, String method, … ) vararg

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

Register a property value change for “undo”.

  • void add_undo_reference ( Object object )

Register a reference for “undo” that will be erased if the “undo” history is lost. This is useful mostly for nodes removed with the “do” call (not the “undo” call!).

  • void clear_history ( bool increase_version=true )

Clear the undo/redo history and associated references.

Passing false to increase_version will prevent the version number to be increased from this.

  • void commit_action ( )

Commit the action. All “do” methods/properties are called/set when this function is called.

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 the merge_mode argument. See MergeMode for details.

  • String get_current_action_name ( ) const

Gets the name of the current action.

  • int get_version ( ) const

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.

Returns true if a “redo” action is available.

Returns true if an “undo” action is available.

  • bool is_commiting_action ( ) const

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

Redo the last action.

Undo the last action.