godot-docs/classes/class_undoredo.rst

:github_url: hide

.. Generated automatically by doc/tools/make_rst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the UndoRedo.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.

.. _class_UndoRedo:

UndoRedo
========

**Inherits:** :ref:`Object<class_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()

:ref:`create_action<class_UndoRedo_method_create_action>`, :ref:`add_do_method<class_UndoRedo_method_add_do_method>`, :ref:`add_undo_method<class_UndoRedo_method_add_undo_method>`, :ref:`add_do_property<class_UndoRedo_method_add_do_property>`, :ref:`add_undo_property<class_UndoRedo_method_add_undo_property>`, and :ref:`commit_action<class_UndoRedo_method_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 :ref:`add_do_method<class_UndoRedo_method_add_do_method>` and :ref:`add_undo_method<class_UndoRedo_method_add_undo_method>` out; the same goes for properties. You can also register more than one method/property.

Methods
-------

+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                        | :ref:`add_do_method<class_UndoRedo_method_add_do_method>` **(** :ref:`Object<class_Object>` object, :ref:`String<class_String>` method, ... **)** |vararg|                                  |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                        | :ref:`add_do_property<class_UndoRedo_method_add_do_property>` **(** :ref:`Object<class_Object>` object, :ref:`String<class_String>` property, :ref:`Variant<class_Variant>` value **)**     |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                        | :ref:`add_do_reference<class_UndoRedo_method_add_do_reference>` **(** :ref:`Object<class_Object>` object **)**                                                                              |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                        | :ref:`add_undo_method<class_UndoRedo_method_add_undo_method>` **(** :ref:`Object<class_Object>` object, :ref:`String<class_String>` method, ... **)** |vararg|                              |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                        | :ref:`add_undo_property<class_UndoRedo_method_add_undo_property>` **(** :ref:`Object<class_Object>` object, :ref:`String<class_String>` property, :ref:`Variant<class_Variant>` value **)** |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                        | :ref:`add_undo_reference<class_UndoRedo_method_add_undo_reference>` **(** :ref:`Object<class_Object>` object **)**                                                                          |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                        | :ref:`clear_history<class_UndoRedo_method_clear_history>` **(** :ref:`bool<class_bool>` increase_version=true **)**                                                                         |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                        | :ref:`commit_action<class_UndoRedo_method_commit_action>` **(** **)**                                                                                                                       |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                        | :ref:`create_action<class_UndoRedo_method_create_action>` **(** :ref:`String<class_String>` name, :ref:`MergeMode<enum_UndoRedo_MergeMode>` merge_mode=0 **)**                              |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`get_current_action_name<class_UndoRedo_method_get_current_action_name>` **(** **)** |const|                                                                                           |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`       | :ref:`get_version<class_UndoRedo_method_get_version>` **(** **)** |const|                                                                                                                   |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`     | :ref:`has_redo<class_UndoRedo_method_has_redo>` **(** **)** |const|                                                                                                                         |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`     | :ref:`has_undo<class_UndoRedo_method_has_undo>` **(** **)** |const|                                                                                                                         |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`     | :ref:`is_commiting_action<class_UndoRedo_method_is_commiting_action>` **(** **)** |const|                                                                                                   |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`     | :ref:`redo<class_UndoRedo_method_redo>` **(** **)**                                                                                                                                         |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`     | :ref:`undo<class_UndoRedo_method_undo>` **(** **)**                                                                                                                                         |
+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Signals
-------

.. _class_UndoRedo_signal_version_changed:

- **version_changed** **(** **)**

Called when :ref:`undo<class_UndoRedo_method_undo>` or :ref:`redo<class_UndoRedo_method_redo>` was called.

Enumerations
------------

.. _enum_UndoRedo_MergeMode:

.. _class_UndoRedo_constant_MERGE_DISABLE:

.. _class_UndoRedo_constant_MERGE_ENDS:

.. _class_UndoRedo_constant_MERGE_ALL:

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
-------------------

.. _class_UndoRedo_method_add_do_method:

- void **add_do_method** **(** :ref:`Object<class_Object>` object, :ref:`String<class_String>` method, ... **)** |vararg|

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

----

.. _class_UndoRedo_method_add_do_property:

- void **add_do_property** **(** :ref:`Object<class_Object>` object, :ref:`String<class_String>` property, :ref:`Variant<class_Variant>` value **)**

Register a property value change for "do".

----

.. _class_UndoRedo_method_add_do_reference:

- void **add_do_reference** **(** :ref:`Object<class_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.

----

.. _class_UndoRedo_method_add_undo_method:

- void **add_undo_method** **(** :ref:`Object<class_Object>` object, :ref:`String<class_String>` method, ... **)** |vararg|

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

----

.. _class_UndoRedo_method_add_undo_property:

- void **add_undo_property** **(** :ref:`Object<class_Object>` object, :ref:`String<class_String>` property, :ref:`Variant<class_Variant>` value **)**

Register a property value change for "undo".

----

.. _class_UndoRedo_method_add_undo_reference:

- void **add_undo_reference** **(** :ref:`Object<class_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!).

----

.. _class_UndoRedo_method_clear_history:

- void **clear_history** **(** :ref:`bool<class_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.

----

.. _class_UndoRedo_method_commit_action:

- void **commit_action** **(** **)**

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

----

.. _class_UndoRedo_method_create_action:

- void **create_action** **(** :ref:`String<class_String>` name, :ref:`MergeMode<enum_UndoRedo_MergeMode>` merge_mode=0 **)**

Create a new action. After this is called, do all your calls to :ref:`add_do_method<class_UndoRedo_method_add_do_method>`, :ref:`add_undo_method<class_UndoRedo_method_add_undo_method>`, :ref:`add_do_property<class_UndoRedo_method_add_do_property>`, and :ref:`add_undo_property<class_UndoRedo_method_add_undo_property>`, then commit the action with :ref:`commit_action<class_UndoRedo_method_commit_action>`.

The way actions are merged is dictated by the ``merge_mode`` argument. See :ref:`MergeMode<enum_UndoRedo_MergeMode>` for details.

----

.. _class_UndoRedo_method_get_current_action_name:

- :ref:`String<class_String>` **get_current_action_name** **(** **)** |const|

Gets the name of the current action.

----

.. _class_UndoRedo_method_get_version:

- :ref:`int<class_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.

----

.. _class_UndoRedo_method_has_redo:

- :ref:`bool<class_bool>` **has_redo** **(** **)** |const|

Returns ``true`` if a "redo" action is available.

----

.. _class_UndoRedo_method_has_undo:

- :ref:`bool<class_bool>` **has_undo** **(** **)** |const|

Returns ``true`` if an "undo" action is available.

----

.. _class_UndoRedo_method_is_commiting_action:

- :ref:`bool<class_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 :ref:`commit_action<class_UndoRedo_method_commit_action>`).

----

.. _class_UndoRedo_method_redo:

- :ref:`bool<class_bool>` **redo** **(** **)**

Redo the last action.

----

.. _class_UndoRedo_method_undo:

- :ref:`bool<class_bool>` **undo** **(** **)**

Undo the last action.

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`