Merge pull request #76688 from ajreckof/backward_undo

Add `backward_undo_ops` as option for action

2 files changed, 35 insertions, 2 deletions

diff --git a/doc/classes/EditorUndoRedoManager.xml b/doc/classes/EditorUndoRedoManager.xml
index aaf74ebbe0..553e36bd42 100644
--- a/doc/classes/EditorUndoRedoManager.xml
+++ b/doc/classes/EditorUndoRedoManager.xml
@@ -80,10 +80,12 @@
 			<param index="0" name="name" type="String" />
 			<param index="1" name="merge_mode" type="int" enum="UndoRedo.MergeMode" default="0" />
 			<param index="2" name="custom_context" type="Object" default="null" />
+			<param index="3" name="backward_undo_ops" type="bool" default="false" />
 			<description>
 				Create a new action. After this is called, do all your calls to [method add_do_method], [method add_undo_method], [method add_do_property], and [method add_undo_property], then commit the action with [method commit_action].
 				The way actions are merged is dictated by the [param merge_mode] argument. See [enum UndoRedo.MergeMode] for details.
 				If [param custom_context] object is provided, it will be used for deducing target history (instead of using the first operation).
+				The way undo operation are ordered in actions is dictated by [param backward_undo_ops]. When [param backward_undo_ops] is [code]false[/code] 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.
 			</description>
 		</method>
 		<method name="get_history_undo_redo" qualifiers="const">
diff --git a/doc/classes/UndoRedo.xml b/doc/classes/UndoRedo.xml
index 9b9bf7f569..d2b0bbb0ca 100644
--- a/doc/classes/UndoRedo.xml
+++ b/doc/classes/UndoRedo.xml
@@ -56,9 +56,38 @@
 		}
 		[/csharp]
 		[/codeblocks]
-		[method create_action], [method add_do_method], [method add_undo_method], [method add_do_property], [method add_undo_property], and [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 [method add_do_method] and [method add_undo_method] out; the same goes for properties. You can also register more than one method/property in the order they should run.
+		Before calling any of the [code]add_(un)do_*[/code] methods, you need to first call [method create_action]. Afterwards you need to call [method commit_action].
+		If you don't need to register a method, you can leave [method add_do_method] and [method add_undo_method] out; the same goes for properties. You can also register more than one method/property.
 		If you are making an [EditorPlugin] and want to integrate into the editor's undo history, use [EditorUndoRedoManager] instead.
+		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.
+		[codeblocks]
+		[gdscript]
+		undo_redo.create_action("Add object")
+
+		# DO
+		undo_redo.add_do_method(_create_object)
+		undo_redo.add_do_method(_add_object_to_singleton)
+
+		# UNDO
+		undo_redo.add_undo_method(_remove_object_from_singleton)
+		undo_redo.add_undo_method(_destroy_that_object)
+
+		undo_redo.commit_action()
+		[/gdscript]
+		[csharp]
+		_undo_redo.CreateAction("Add object");
+
+		// DO
+		_undo_redo.AddDoMethod(new Callable(this, MethodName.CreateObject));
+		_undo_redo.AddDoMethod(new Callable(this, MethodName.AddObjectToSingleton));
+
+		// UNDO
+		_undo_redo.AddUndoMethod(new Callable(this, MethodName.RemoveObjectFromSingleton));
+		_undo_redo.AddUndoMethod(new Callable(this, MethodName.DestroyThatObject));
+
+		_undo_redo.CommitAction();
+		[/csharp]
+		[/codeblocks]
 	</description>
 	<tutorials>
 	</tutorials>
@@ -144,9 +173,11 @@
 			<return type="void" />
 			<param index="0" name="name" type="String" />
 			<param index="1" name="merge_mode" type="int" enum="UndoRedo.MergeMode" default="0" />
+			<param index="2" name="backward_undo_ops" type="bool" default="false" />
 			<description>
 				Create a new action. After this is called, do all your calls to [method add_do_method], [method add_undo_method], [method add_do_property], and [method add_undo_property], then commit the action with [method commit_action].
 				The way actions are merged is dictated by [param merge_mode]. See [enum MergeMode] for details.
+				The way undo operation are ordered in actions is dictated by [param backward_undo_ops]. When [param backward_undo_ops] is [code]false[/code] 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.
 			</description>
 		</method>
 		<method name="end_force_keep_in_merge_ends">