class_undoredo.rst 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520
  1. :github_url: hide
  2. .. DO NOT EDIT THIS FILE!!!
  3. .. Generated automatically from Godot engine sources.
  4. .. Generator: https://github.com/godotengine/godot/tree/4.1/doc/tools/make_rst.py.
  5. .. XML source: https://github.com/godotengine/godot/tree/4.1/doc/classes/UndoRedo.xml.
  6. .. _class_UndoRedo:
  7. UndoRedo
  8. ========
  9. **Inherits:** :ref:`Object<class_Object>`
  10. Provides a high-level interface for implementing undo and redo operations.
  11. .. rst-class:: classref-introduction-group
  12. Description
  13. -----------
  14. 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.
  15. When an action is committed, all of the ``do_*`` methods will run. If the :ref:`undo<class_UndoRedo_method_undo>` method is used, the ``undo_*`` methods will run. If the :ref:`redo<class_UndoRedo_method_redo>` method is used, once again, all of the ``do_*`` methods will run.
  16. Here's an example on how to add an action:
  17. .. tabs::
  18. .. code-tab:: gdscript
  19. var undo_redo = UndoRedo.new()
  20. func do_something():
  21. pass # Put your code here.
  22. func undo_something():
  23. pass # Put here the code that reverts what's done by "do_something()".
  24. func _on_my_button_pressed():
  25. var node = get_node("MyNode2D")
  26. undo_redo.create_action("Move the node")
  27. undo_redo.add_do_method(do_something)
  28. undo_redo.add_undo_method(undo_something)
  29. undo_redo.add_do_property(node, "position", Vector2(100,100))
  30. undo_redo.add_undo_property(node, "position", node.position)
  31. undo_redo.commit_action()
  32. .. code-tab:: csharp
  33. private UndoRedo _undoRedo;
  34. public override void _Ready()
  35. {
  36. _undoRedo = new UndoRedo();
  37. }
  38. public void DoSomething()
  39. {
  40. // Put your code here.
  41. }
  42. public void UndoSomething()
  43. {
  44. // Put here the code that reverts what's done by "DoSomething()".
  45. }
  46. private void OnMyButtonPressed()
  47. {
  48. var node = GetNode<Node2D>("MyNode2D");
  49. _undoRedo.CreateAction("Move the node");
  50. _undoRedo.AddDoMethod(new Callable(this, MethodName.DoSomething));
  51. _undoRedo.AddUndoMethod(new Callable(this, MethodName.UndoSomething));
  52. _undoRedo.AddDoProperty(node, "position", new Vector2(100, 100));
  53. _undoRedo.AddUndoProperty(node, "position", node.Position);
  54. _undoRedo.CommitAction();
  55. }
  56. Before calling any of the ``add_(un)do_*`` methods, you need to first call :ref:`create_action<class_UndoRedo_method_create_action>`. Afterwards you need to call :ref:`commit_action<class_UndoRedo_method_commit_action>`.
  57. 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.
  58. 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.
  59. 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.
  60. .. tabs::
  61. .. code-tab:: gdscript
  62. undo_redo.create_action("Add object")
  63. # DO
  64. undo_redo.add_do_method(_create_object)
  65. undo_redo.add_do_method(_add_object_to_singleton)
  66. # UNDO
  67. undo_redo.add_undo_method(_remove_object_from_singleton)
  68. undo_redo.add_undo_method(_destroy_that_object)
  69. undo_redo.commit_action()
  70. .. code-tab:: csharp
  71. _undo_redo.CreateAction("Add object");
  72. // DO
  73. _undo_redo.AddDoMethod(new Callable(this, MethodName.CreateObject));
  74. _undo_redo.AddDoMethod(new Callable(this, MethodName.AddObjectToSingleton));
  75. // UNDO
  76. _undo_redo.AddUndoMethod(new Callable(this, MethodName.RemoveObjectFromSingleton));
  77. _undo_redo.AddUndoMethod(new Callable(this, MethodName.DestroyThatObject));
  78. _undo_redo.CommitAction();
  79. .. rst-class:: classref-reftable-group
  80. Methods
  81. -------
  82. .. table::
  83. :widths: auto
  84. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  85. | void | :ref:`add_do_method<class_UndoRedo_method_add_do_method>` **(** :ref:`Callable<class_Callable>` callable **)** |
  86. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  87. | 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 **)** |
  88. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  89. | void | :ref:`add_do_reference<class_UndoRedo_method_add_do_reference>` **(** :ref:`Object<class_Object>` object **)** |
  90. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  91. | void | :ref:`add_undo_method<class_UndoRedo_method_add_undo_method>` **(** :ref:`Callable<class_Callable>` callable **)** |
  92. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  93. | 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 **)** |
  94. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  95. | void | :ref:`add_undo_reference<class_UndoRedo_method_add_undo_reference>` **(** :ref:`Object<class_Object>` object **)** |
  96. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  97. | void | :ref:`clear_history<class_UndoRedo_method_clear_history>` **(** :ref:`bool<class_bool>` increase_version=true **)** |
  98. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  99. | void | :ref:`commit_action<class_UndoRedo_method_commit_action>` **(** :ref:`bool<class_bool>` execute=true **)** |
  100. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  101. | void | :ref:`create_action<class_UndoRedo_method_create_action>` **(** :ref:`String<class_String>` name, :ref:`MergeMode<enum_UndoRedo_MergeMode>` merge_mode=0, :ref:`bool<class_bool>` backward_undo_ops=false **)** |
  102. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  103. | void | :ref:`end_force_keep_in_merge_ends<class_UndoRedo_method_end_force_keep_in_merge_ends>` **(** **)** |
  104. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  105. | :ref:`String<class_String>` | :ref:`get_action_name<class_UndoRedo_method_get_action_name>` **(** :ref:`int<class_int>` id **)** |
  106. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  107. | :ref:`int<class_int>` | :ref:`get_current_action<class_UndoRedo_method_get_current_action>` **(** **)** |
  108. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  109. | :ref:`String<class_String>` | :ref:`get_current_action_name<class_UndoRedo_method_get_current_action_name>` **(** **)** |const| |
  110. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  111. | :ref:`int<class_int>` | :ref:`get_history_count<class_UndoRedo_method_get_history_count>` **(** **)** |
  112. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  113. | :ref:`int<class_int>` | :ref:`get_version<class_UndoRedo_method_get_version>` **(** **)** |const| |
  114. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  115. | :ref:`bool<class_bool>` | :ref:`has_redo<class_UndoRedo_method_has_redo>` **(** **)** |const| |
  116. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  117. | :ref:`bool<class_bool>` | :ref:`has_undo<class_UndoRedo_method_has_undo>` **(** **)** |const| |
  118. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  119. | :ref:`bool<class_bool>` | :ref:`is_committing_action<class_UndoRedo_method_is_committing_action>` **(** **)** |const| |
  120. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  121. | :ref:`bool<class_bool>` | :ref:`redo<class_UndoRedo_method_redo>` **(** **)** |
  122. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  123. | void | :ref:`start_force_keep_in_merge_ends<class_UndoRedo_method_start_force_keep_in_merge_ends>` **(** **)** |
  124. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  125. | :ref:`bool<class_bool>` | :ref:`undo<class_UndoRedo_method_undo>` **(** **)** |
  126. +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  127. .. rst-class:: classref-section-separator
  128. ----
  129. .. rst-class:: classref-descriptions-group
  130. Signals
  131. -------
  132. .. _class_UndoRedo_signal_version_changed:
  133. .. rst-class:: classref-signal
  134. **version_changed** **(** **)**
  135. Called when :ref:`undo<class_UndoRedo_method_undo>` or :ref:`redo<class_UndoRedo_method_redo>` was called.
  136. .. rst-class:: classref-section-separator
  137. ----
  138. .. rst-class:: classref-descriptions-group
  139. Enumerations
  140. ------------
  141. .. _enum_UndoRedo_MergeMode:
  142. .. rst-class:: classref-enumeration
  143. enum **MergeMode**:
  144. .. _class_UndoRedo_constant_MERGE_DISABLE:
  145. .. rst-class:: classref-enumeration-constant
  146. :ref:`MergeMode<enum_UndoRedo_MergeMode>` **MERGE_DISABLE** = ``0``
  147. Makes "do"/"undo" operations stay in separate actions.
  148. .. _class_UndoRedo_constant_MERGE_ENDS:
  149. .. rst-class:: classref-enumeration-constant
  150. :ref:`MergeMode<enum_UndoRedo_MergeMode>` **MERGE_ENDS** = ``1``
  151. 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.
  152. .. _class_UndoRedo_constant_MERGE_ALL:
  153. .. rst-class:: classref-enumeration-constant
  154. :ref:`MergeMode<enum_UndoRedo_MergeMode>` **MERGE_ALL** = ``2``
  155. Makes subsequent actions with the same name be merged into one.
  156. .. rst-class:: classref-section-separator
  157. ----
  158. .. rst-class:: classref-descriptions-group
  159. Method Descriptions
  160. -------------------
  161. .. _class_UndoRedo_method_add_do_method:
  162. .. rst-class:: classref-method
  163. void **add_do_method** **(** :ref:`Callable<class_Callable>` callable **)**
  164. Register a :ref:`Callable<class_Callable>` that will be called when the action is committed.
  165. .. rst-class:: classref-item-separator
  166. ----
  167. .. _class_UndoRedo_method_add_do_property:
  168. .. rst-class:: classref-method
  169. void **add_do_property** **(** :ref:`Object<class_Object>` object, :ref:`StringName<class_StringName>` property, :ref:`Variant<class_Variant>` value **)**
  170. Register a ``property`` that would change its value to ``value`` when the action is committed.
  171. .. rst-class:: classref-item-separator
  172. ----
  173. .. _class_UndoRedo_method_add_do_reference:
  174. .. rst-class:: classref-method
  175. void **add_do_reference** **(** :ref:`Object<class_Object>` object **)**
  176. 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.
  177. ::
  178. var node = Node2D.new()
  179. undo_redo.create_action("Add node")
  180. undo_redo.add_do_method(add_child.bind(node))
  181. undo_redo.add_do_reference(node)
  182. undo_redo.add_undo_method(remove_child.bind(node))
  183. undo_redo.commit_action()
  184. .. rst-class:: classref-item-separator
  185. ----
  186. .. _class_UndoRedo_method_add_undo_method:
  187. .. rst-class:: classref-method
  188. void **add_undo_method** **(** :ref:`Callable<class_Callable>` callable **)**
  189. Register a :ref:`Callable<class_Callable>` that will be called when the action is undone.
  190. .. rst-class:: classref-item-separator
  191. ----
  192. .. _class_UndoRedo_method_add_undo_property:
  193. .. rst-class:: classref-method
  194. void **add_undo_property** **(** :ref:`Object<class_Object>` object, :ref:`StringName<class_StringName>` property, :ref:`Variant<class_Variant>` value **)**
  195. Register a ``property`` that would change its value to ``value`` when the action is undone.
  196. .. rst-class:: classref-item-separator
  197. ----
  198. .. _class_UndoRedo_method_add_undo_reference:
  199. .. rst-class:: classref-method
  200. void **add_undo_reference** **(** :ref:`Object<class_Object>` object **)**
  201. 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!).
  202. ::
  203. var node = $Node2D
  204. undo_redo.create_action("Remove node")
  205. undo_redo.add_do_method(remove_child.bind(node))
  206. undo_redo.add_undo_method(add_child.bind(node))
  207. undo_redo.add_undo_reference(node)
  208. undo_redo.commit_action()
  209. .. rst-class:: classref-item-separator
  210. ----
  211. .. _class_UndoRedo_method_clear_history:
  212. .. rst-class:: classref-method
  213. void **clear_history** **(** :ref:`bool<class_bool>` increase_version=true **)**
  214. Clear the undo/redo history and associated references.
  215. Passing ``false`` to ``increase_version`` will prevent the version number from increasing when the history is cleared.
  216. .. rst-class:: classref-item-separator
  217. ----
  218. .. _class_UndoRedo_method_commit_action:
  219. .. rst-class:: classref-method
  220. void **commit_action** **(** :ref:`bool<class_bool>` execute=true **)**
  221. Commit the action. If ``execute`` is ``true`` (which it is by default), all "do" methods/properties are called/set when this function is called.
  222. .. rst-class:: classref-item-separator
  223. ----
  224. .. _class_UndoRedo_method_create_action:
  225. .. rst-class:: classref-method
  226. void **create_action** **(** :ref:`String<class_String>` name, :ref:`MergeMode<enum_UndoRedo_MergeMode>` merge_mode=0, :ref:`bool<class_bool>` backward_undo_ops=false **)**
  227. 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>`.
  228. The way actions are merged is dictated by ``merge_mode``. See :ref:`MergeMode<enum_UndoRedo_MergeMode>` for details.
  229. 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.
  230. .. rst-class:: classref-item-separator
  231. ----
  232. .. _class_UndoRedo_method_end_force_keep_in_merge_ends:
  233. .. rst-class:: classref-method
  234. void **end_force_keep_in_merge_ends** **(** **)**
  235. 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>`.
  236. .. rst-class:: classref-item-separator
  237. ----
  238. .. _class_UndoRedo_method_get_action_name:
  239. .. rst-class:: classref-method
  240. :ref:`String<class_String>` **get_action_name** **(** :ref:`int<class_int>` id **)**
  241. Gets the action name from its index.
  242. .. rst-class:: classref-item-separator
  243. ----
  244. .. _class_UndoRedo_method_get_current_action:
  245. .. rst-class:: classref-method
  246. :ref:`int<class_int>` **get_current_action** **(** **)**
  247. Gets the index of the current action.
  248. .. rst-class:: classref-item-separator
  249. ----
  250. .. _class_UndoRedo_method_get_current_action_name:
  251. .. rst-class:: classref-method
  252. :ref:`String<class_String>` **get_current_action_name** **(** **)** |const|
  253. Gets the name of the current action, equivalent to ``get_action_name(get_current_action())``.
  254. .. rst-class:: classref-item-separator
  255. ----
  256. .. _class_UndoRedo_method_get_history_count:
  257. .. rst-class:: classref-method
  258. :ref:`int<class_int>` **get_history_count** **(** **)**
  259. Returns how many elements are in the history.
  260. .. rst-class:: classref-item-separator
  261. ----
  262. .. _class_UndoRedo_method_get_version:
  263. .. rst-class:: classref-method
  264. :ref:`int<class_int>` **get_version** **(** **)** |const|
  265. Gets the version. Every time a new action is committed, the **UndoRedo**'s version number is increased automatically.
  266. This is useful mostly to check if something changed from a saved version.
  267. .. rst-class:: classref-item-separator
  268. ----
  269. .. _class_UndoRedo_method_has_redo:
  270. .. rst-class:: classref-method
  271. :ref:`bool<class_bool>` **has_redo** **(** **)** |const|
  272. Returns ``true`` if a "redo" action is available.
  273. .. rst-class:: classref-item-separator
  274. ----
  275. .. _class_UndoRedo_method_has_undo:
  276. .. rst-class:: classref-method
  277. :ref:`bool<class_bool>` **has_undo** **(** **)** |const|
  278. Returns ``true`` if an "undo" action is available.
  279. .. rst-class:: classref-item-separator
  280. ----
  281. .. _class_UndoRedo_method_is_committing_action:
  282. .. rst-class:: classref-method
  283. :ref:`bool<class_bool>` **is_committing_action** **(** **)** |const|
  284. 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>`).
  285. .. rst-class:: classref-item-separator
  286. ----
  287. .. _class_UndoRedo_method_redo:
  288. .. rst-class:: classref-method
  289. :ref:`bool<class_bool>` **redo** **(** **)**
  290. Redo the last action.
  291. .. rst-class:: classref-item-separator
  292. ----
  293. .. _class_UndoRedo_method_start_force_keep_in_merge_ends:
  294. .. rst-class:: classref-method
  295. void **start_force_keep_in_merge_ends** **(** **)**
  296. 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>`.
  297. .. rst-class:: classref-item-separator
  298. ----
  299. .. _class_UndoRedo_method_undo:
  300. .. rst-class:: classref-method
  301. :ref:`bool<class_bool>` **undo** **(** **)**
  302. Undo the last action.
  303. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
  304. .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
  305. .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
  306. .. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
  307. .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
  308. .. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`
  309. .. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)`