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.