godot/doc/classes/EditorUndoRedoManager.xml

<?xml version="1.0" encoding="UTF-8" ?>
<class name="EditorUndoRedoManager" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
	<brief_description>
		Manages undo history of scenes opened in the editor.
	</brief_description>
	<description>
		[EditorUndoRedoManager] is a manager for [UndoRedo] objects associated with edited scenes. Each scene has its own undo history and [EditorUndoRedoManager] ensures that each action performed in the editor gets associated with a proper scene. For actions not related to scenes ([ProjectSettings] edits, external resources, etc.), a separate global history is used.
		The usage is mostly the same as [UndoRedo]. You create and commit actions and the manager automatically decides under-the-hood what scenes it belongs to. The scene is deduced based on the first operation in an action, using the object from the operation. The rules are as follows:
		- If the object is a [Node], use the currently edited scene;
		- If the object is a built-in resource, use the scene from its path;
		- If the object is external resource or anything else, use global history.
		This guessing can sometimes yield false results, so you can provide a custom context object when creating an action.
		[EditorUndoRedoManager] is intended to be used by Godot editor plugins. You can obtain it using [method EditorPlugin.get_undo_redo]. For non-editor uses or plugins that don't need to integrate with the editor's undo history, use [UndoRedo] instead.
		The manager's API is mostly the same as in [UndoRedo], so you can refer to its documentation for more examples. The main difference is that [EditorUndoRedoManager] uses object + method name for actions, instead of [Callable].
	</description>
	<tutorials>
	</tutorials>
	<methods>
		<method name="add_do_method" qualifiers="vararg">
			<return type="void" />
			<param index="0" name="object" type="Object" />
			<param index="1" name="method" type="StringName" />
			<description>
				Register a method that will be called when the action is committed (i.e. the "do" action).
				If this is the first operation, the [param object] will be used to deduce target undo history.
			</description>
		</method>
		<method name="add_do_property">
			<return type="void" />
			<param index="0" name="object" type="Object" />
			<param index="1" name="property" type="StringName" />
			<param index="2" name="value" type="Variant" />
			<description>
				Register a property value change for "do".
				If this is the first operation, the [param object] will be used to deduce target undo history.
			</description>
		</method>
		<method name="add_do_reference">
			<return type="void" />
			<param index="0" name="object" type="Object" />
			<description>
				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.
			</description>
		</method>
		<method name="add_undo_method" qualifiers="vararg">
			<return type="void" />
			<param index="0" name="object" type="Object" />
			<param index="1" name="method" type="StringName" />
			<description>
				Register a method that will be called when the action is undone (i.e. the "undo" action).
				If this is the first operation, the [param object] will be used to deduce target undo history.
			</description>
		</method>
		<method name="add_undo_property">
			<return type="void" />
			<param index="0" name="object" type="Object" />
			<param index="1" name="property" type="StringName" />
			<param index="2" name="value" type="Variant" />
			<description>
				Register a property value change for "undo".
				If this is the first operation, the [param object] will be used to deduce target undo history.
			</description>
		</method>
		<method name="add_undo_reference">
			<return type="void" />
			<param index="0" name="object" type="Object" />
			<description>
				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!).
			</description>
		</method>
		<method name="clear_history">
			<return type="void" />
			<param index="0" name="id" type="int" default="-99" />
			<param index="1" name="increase_version" type="bool" default="true" />
			<description>
				Clears the given undo history. You can clear history for a specific scene, global history, or for all scenes at once if [param id] is [constant INVALID_HISTORY].
				If [param increase_version] is [code]true[/code], the undo history version will be increased, marking it as unsaved. Useful for operations that modify the scene, but don't support undo.
				[codeblock]
				var scene_root = EditorInterface.get_edited_scene_root()
				var undo_redo = EditorInterface.get_editor_undo_redo()
				undo_redo.clear_history(undo_redo.get_object_history_id(scene_root))
				[/codeblock]
				[b]Note:[/b] If you want to mark an edited scene as unsaved without clearing its history, use [method EditorInterface.mark_scene_as_unsaved] instead.
			</description>
		</method>
		<method name="commit_action">
			<return type="void" />
			<param index="0" name="execute" type="bool" default="true" />
			<description>
				Commits the action. If [param execute] is [code]true[/code] (default), all "do" methods/properties are called/set when this function is called.
			</description>
		</method>
		<method name="create_action">
			<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="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="force_fixed_history">
			<return type="void" />
			<description>
				Forces the next operation (e.g. [method add_do_method]) to use the action's history rather than guessing it from the object. This is sometimes needed when a history can't be correctly determined, like for a nested resource that doesn't have a path yet.
				This method should only be used when absolutely necessary, otherwise it might cause invalid history state. For most of complex cases, the [code]custom_context[/code] parameter of [method create_action] is sufficient.
			</description>
		</method>
		<method name="get_history_undo_redo" qualifiers="const">
			<return type="UndoRedo" />
			<param index="0" name="id" type="int" />
			<description>
				Returns the [UndoRedo] object associated with the given history [param id].
				[param id] above [code]0[/code] are mapped to the opened scene tabs (but it doesn't match their order). [param id] of [code]0[/code] or lower have special meaning (see [enum SpecialHistory]).
				Best used with [method get_object_history_id]. This method is only provided in case you need some more advanced methods of [UndoRedo] (but keep in mind that directly operating on the [UndoRedo] object might affect editor's stability).
			</description>
		</method>
		<method name="get_object_history_id" qualifiers="const">
			<return type="int" />
			<param index="0" name="object" type="Object" />
			<description>
				Returns the history ID deduced from the given [param object]. It can be used with [method get_history_undo_redo].
			</description>
		</method>
		<method name="is_committing_action" qualifiers="const">
			<return type="bool" />
			<description>
				Returns [code]true[/code] if the [EditorUndoRedoManager] is currently committing the action, i.e. running its "do" method or property change (see [method commit_action]).
			</description>
		</method>
	</methods>
	<signals>
		<signal name="history_changed">
			<description>
				Emitted when the list of actions in any history has changed, either when an action is committed or a history is cleared.
			</description>
		</signal>
		<signal name="version_changed">
			<description>
				Emitted when the version of any history has changed as a result of undo or redo call.
			</description>
		</signal>
	</signals>
	<constants>
		<constant name="GLOBAL_HISTORY" value="0" enum="SpecialHistory">
			Global history not associated with any scene, but with external resources etc.
		</constant>
		<constant name="REMOTE_HISTORY" value="-9" enum="SpecialHistory">
			History associated with remote inspector. Used when live editing a running project.
		</constant>
		<constant name="INVALID_HISTORY" value="-99" enum="SpecialHistory">
			Invalid "null" history. It's a special value, not associated with any object.
		</constant>
	</constants>
</class>