godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-04 14:11:02 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
6febc8ee06484a44430ef3a8e5bebabd1f502e93
godot-docs/classes/class_undoredo.rst
Godot Organization 6febc8ee06 classref: Sync with current master branch (c64afeb)
2023-05-13 03:19:02 +00:00

483 lines
22 KiB
ReStructuredText
Raw Blame History

:github_url: hide
.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/UndoRedo.xml.
.. _class_UndoRedo:
UndoRedo
========
**Inherits:** :ref:`Object<class_Object>`
General-purpose helper to manage undo/redo operations.
.. rst-class:: classref-introduction-group
Description
-----------
UndoRedo 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 UndoRedo action:
.. tabs::
.. code-tab:: gdscript
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()
.. code-tab:: csharp
private UndoRedo _undoRedo;
public override void _Ready()
{
_undoRedo = new UndoRedo();
}
public void DoSomething()
{
// Put your code here.
}
public void UndoSomething()
{
// Put here the code that reverts what's done by "DoSomething()".
}
private void OnMyButtonPressed()
{
var node = GetNode<Node2D>("MyNode2D");
_undoRedo.CreateAction("Move the node");
_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();
}
\ :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.
If you are making an :ref:`EditorPlugin<class_EditorPlugin>` and want to integrate into the editor's undo history, use :ref:`EditorUndoRedoManager<class_EditorUndoRedoManager>` instead.
.. rst-class:: classref-reftable-group
Methods
-------
.. table::
:widths: auto
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`add_do_method<class_UndoRedo_method_add_do_method>` **(** :ref:`Callable<class_Callable>` callable **)** |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`add_do_property<class_UndoRedo_method_add_do_property>` **(** :ref:`Object<class_Object>` object, :ref:`StringName<class_StringName>` 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:`Callable<class_Callable>` callable **)** |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`add_undo_property<class_UndoRedo_method_add_undo_property>` **(** :ref:`Object<class_Object>` object, :ref:`StringName<class_StringName>` 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>` **(** :ref:`bool<class_bool>` execute=true **)** |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`create_action<class_UndoRedo_method_create_action>` **(** :ref:`String<class_String>` name, :ref:`MergeMode<enum_UndoRedo_MergeMode>` merge_mode=0 **)** |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`end_force_keep_in_merge_ends<class_UndoRedo_method_end_force_keep_in_merge_ends>` **(** **)** |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`get_action_name<class_UndoRedo_method_get_action_name>` **(** :ref:`int<class_int>` id **)** |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_current_action<class_UndoRedo_method_get_current_action>` **(** **)** |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`get_current_action_name<class_UndoRedo_method_get_current_action_name>` **(** **)** |const| |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_history_count<class_UndoRedo_method_get_history_count>` **(** **)** |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :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_committing_action<class_UndoRedo_method_is_committing_action>` **(** **)** |const| |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`redo<class_UndoRedo_method_redo>` **(** **)** |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`start_force_keep_in_merge_ends<class_UndoRedo_method_start_force_keep_in_merge_ends>` **(** **)** |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`undo<class_UndoRedo_method_undo>` **(** **)** |
+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Signals
-------
.. _class_UndoRedo_signal_version_changed:
.. rst-class:: classref-signal
**version_changed** **(** **)**
Called when :ref:`undo<class_UndoRedo_method_undo>` or :ref:`redo<class_UndoRedo_method_redo>` was called.
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Enumerations
------------
.. _enum_UndoRedo_MergeMode:
.. rst-class:: classref-enumeration
enum **MergeMode**:
.. _class_UndoRedo_constant_MERGE_DISABLE:
.. rst-class:: classref-enumeration-constant
:ref:`MergeMode<enum_UndoRedo_MergeMode>` **MERGE_DISABLE** = ``0``
Makes "do"/"undo" operations stay in separate actions.
.. _class_UndoRedo_constant_MERGE_ENDS:
.. rst-class:: classref-enumeration-constant
:ref:`MergeMode<enum_UndoRedo_MergeMode>` **MERGE_ENDS** = ``1``
Makes so that the action's "undo" operations are from the first action created and the "do" operations are from the last subsequent action with the same name.
.. _class_UndoRedo_constant_MERGE_ALL:
.. rst-class:: classref-enumeration-constant
:ref:`MergeMode<enum_UndoRedo_MergeMode>` **MERGE_ALL** = ``2``
Makes subsequent actions with the same name be merged into one.
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Method Descriptions
-------------------
.. _class_UndoRedo_method_add_do_method:
.. rst-class:: classref-method
void **add_do_method** **(** :ref:`Callable<class_Callable>` callable **)**
Register a :ref:`Callable<class_Callable>` that will be called when the action is committed.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_add_do_property:
.. rst-class:: classref-method
void **add_do_property** **(** :ref:`Object<class_Object>` object, :ref:`StringName<class_StringName>` property, :ref:`Variant<class_Variant>` value **)**
Register a ``property`` that would change its value to ``value`` when the action is committed.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_add_do_reference:
.. rst-class:: classref-method
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.
::
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()
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_add_undo_method:
.. rst-class:: classref-method
void **add_undo_method** **(** :ref:`Callable<class_Callable>` callable **)**
Register a :ref:`Callable<class_Callable>` that will be called when the action is undone.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_add_undo_property:
.. rst-class:: classref-method
void **add_undo_property** **(** :ref:`Object<class_Object>` object, :ref:`StringName<class_StringName>` property, :ref:`Variant<class_Variant>` value **)**
Register a ``property`` that would change its value to ``value`` when the action is undone.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_add_undo_reference:
.. rst-class:: classref-method
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!).
::
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()
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_clear_history:
.. rst-class:: classref-method
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 from increasing when the history is cleared.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_commit_action:
.. rst-class:: classref-method
void **commit_action** **(** :ref:`bool<class_bool>` execute=true **)**
Commit the action. If ``execute`` is ``true`` (which it is by default), all "do" methods/properties are called/set when this function is called.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_create_action:
.. rst-class:: classref-method
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 ``merge_mode``. See :ref:`MergeMode<enum_UndoRedo_MergeMode>` for details.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_end_force_keep_in_merge_ends:
.. rst-class:: classref-method
void **end_force_keep_in_merge_ends** **(** **)**
Stops marking operations as to be processed even if the action gets merged with another in the :ref:`MERGE_ENDS<class_UndoRedo_constant_MERGE_ENDS>` mode. See :ref:`start_force_keep_in_merge_ends<class_UndoRedo_method_start_force_keep_in_merge_ends>`.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_get_action_name:
.. rst-class:: classref-method
:ref:`String<class_String>` **get_action_name** **(** :ref:`int<class_int>` id **)**
Gets the action name from its index.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_get_current_action:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_current_action** **(** **)**
Gets the index of the current action.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_get_current_action_name:
.. rst-class:: classref-method
:ref:`String<class_String>` **get_current_action_name** **(** **)** |const|
Gets the name of the current action, equivalent to ``get_action_name(get_current_action())``.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_get_history_count:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_history_count** **(** **)**
Returns how many elements are in the history.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_get_version:
.. rst-class:: classref-method
: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.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_has_redo:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **has_redo** **(** **)** |const|
Returns ``true`` if a "redo" action is available.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_has_undo:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **has_undo** **(** **)** |const|
Returns ``true`` if an "undo" action is available.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_is_committing_action:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **is_committing_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>`).
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_redo:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **redo** **(** **)**
Redo the last action.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_start_force_keep_in_merge_ends:
.. rst-class:: classref-method
void **start_force_keep_in_merge_ends** **(** **)**
Marks the next "do" and "undo" operations to be processed even if the action gets merged with another in the :ref:`MERGE_ENDS<class_UndoRedo_constant_MERGE_ENDS>` mode. Return to normal operation using :ref:`end_force_keep_in_merge_ends<class_UndoRedo_method_end_force_keep_in_merge_ends>`.
.. rst-class:: classref-item-separator
----
.. _class_UndoRedo_method_undo:
.. rst-class:: classref-method
: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.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`
Reference in New Issue View Git Blame Copy Permalink