Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

UndoRedo

Hérite de : Object

Provides a high-level interface for implementing undo and redo operations.

Description

UndoRedo fonctionne en enregistrant des changements de méthode et de propriété dans des "actions". Vous pouvez créer une action, puis fournir des moyens de faire et annuler cette action en utilisant des appels de fonction et des modifications de propriété, puis commit l'action.

Lorsqu'une action est commit, toutes les méthodes do_* s'exécuteront. Si la méthode undo() est utilisée, les méthodes undo_* s'exécuteront. Si la méthode redo() est utilisée, une fois de plus, toutes les méthodes do_* seront exécutées.

Voici un exemple de comment d'ajouter une action :

var undo_redo = UndoRedo.new()

func faire_quelque_chose():
    pass # Mettez votre code ici.

func defaire_quelque_chose():
    pass # Mettez ici le code qui annule ce qui est fait par "faire_quelque_chose()".

func _on_my_button_pressed():
    var noeud = get_node("MyNode2D")
    undo_redo.create_action("Déplacer le noeud")
    undo_redo.add_do_method(faire_quelque_chose)
    undo_redo.add_undo_method(defaire_quelque_chose)
    undo_redo.add_do_property(noeud, "position", Vector2(100, 100))
    undo_redo.add_undo_property(noeud, "position", noeud.position)
    undo_redo.commit_action()

private UndoRedo _undoRedo;

public override void _Ready()
{
    _undoRedo = new UndoRedo();
}

public void FaireQuelquechose()
{
    // Mettez votre code ici.
}

public void DefaireQuelquechose()
{
    // Mettez ici le code qui annule ce qui est fait par "FaireQuelquechose()".
}

private void OnMyButtonPressed()
{
    var noeud = GetNode<Node2D>("MyNode2D");
    _undoRedo.CreateAction("Déplacer le noeud");
    _undoRedo.AddDoMethod(new Callable(this, MethodName.FaireQuelquechose));
    _undoRedo.AddUndoMethod(new Callable(this, MethodName.DefaireQuelquechose));
    _undoRedo.AddDoProperty(noeud, "position", new Vector2(100, 100));
    _undoRedo.AddUndoProperty(noeud, "position", noeud.Position);
    _undoRedo.CommitAction();
}

Avant d'appeler l'une des méthodes add_(un)do_*, vous devez d'abord appeler create_action(). Ensuite, vous devez appeler commit_action().

Si vous n'avez pas besoin d'enregistrer une méthode, vous pouvez ignorer add_do_method() et add_undo_method(), il en va de même pour les propriétés. Vous pouvez également enregistrer plus d'une méthode/propriété.

Si vous faites un EditorPlugin et que vous voulez l'intégrer à l'historique de l'éditeur, utilisez plutôt EditorUndoRedoManager.

Si vous enregistrez plusieurs propriétés/méthodes qui dépendent les unes des autres, soyez conscient que par défaut l'opération d'annulation est appelée dans le même ordre qu'elles ont été ajoutées. Par conséquent, au lieu de regrouper les opérations à faire avec les opérations d'annulation, il est préférable de regrouper les actions à faire d'un côté et les actions à défaire de l'autre, comme indiqué ci-dessous.

undo_redo.create_action("Ajouter objet")

# FAIRE
undo_redo.add_do_method(_creer_objet)
undo_redo.add_do_method(_ajouter_objet_au_singleton)

# UNDO
undo_redo.add_undo_method(_retirer_objet_du_singleton)
undo_redo.add_undo_method(_detruire_cet_objet)

undo_redo.commit_action()

_undo_redo.CreateAction("Ajouter objet");

// DO
_undo_redo.AddDoMethod(new Callable(this, MethodName.CreerObjet));
_undo_redo.AddDoMethod(new Callable(this, MethodName.AjouterObjetAuSingleton));

// UNDO
_undo_redo.AddUndoMethod(new Callable(this, MethodName.RetirerObjetDuSingleton));
_undo_redo.AddUndoMethod(new Callable(this, MethodName.DetruireCetObjet));

_undo_redo.CommitAction();

Propriétés

int

max_steps

0

Méthodes

void	add_do_method(callable: Callable)
void	add_do_property(object: Object, property: StringName, value: Variant)
void	add_do_reference(object: Object)
void	add_undo_method(callable: Callable)
void	add_undo_property(object: Object, property: StringName, value: Variant)
void	add_undo_reference(object: Object)
void	clear_history(increase_version: bool = true)
void	commit_action(execute: bool = true)
void	create_action(name: String, merge_mode: MergeMode = 0, backward_undo_ops: bool = false)
void	end_force_keep_in_merge_ends()
String	get_action_name(id: int)
int	get_current_action()
String	get_current_action_name() const
int	get_history_count()
int	get_version() const
bool	has_redo() const
bool	has_undo() const
bool	is_committing_action() const
bool	redo()
void	start_force_keep_in_merge_ends()
bool	undo()

Signaux

version_changed() 🔗

Appelée quand undo() ou redo() sont appelées.

Énumérations

enum MergeMode: 🔗

MergeMode MERGE_DISABLE = 0

Fait que les opérations "annuler"/"refaire" utilisent des actions séparées.

MergeMode MERGE_ENDS = 1

Merges this action with the previous one if they have the same name. Keeps only the first action's "undo" operations and the last action's "do" operations. Useful for sequential changes to a single value.

MergeMode MERGE_ALL = 2

Merges this action with the previous one if they have the same name.

Descriptions des propriétés

int max_steps = 0 🔗

void set_max_steps(value: int)
int get_max_steps()

The maximum number of steps that can be stored in the undo/redo history. If the number of stored steps exceeds this limit, older steps are removed from history and can no longer be reached by calling undo(). A value of 0 or lower means no limit.

Descriptions des méthodes

void add_do_method(callable: Callable) 🔗

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

void add_do_property(object: Object, property: StringName, value: Variant) 🔗

Register a property that would change its value to value when the action is committed.

void add_do_reference(object: Object) 🔗

Register a reference to an object that will be erased if the "do" history is deleted. This is useful for objects added by the "do" action and removed by the "undo" action.

When the "do" history is deleted, if the object is a RefCounted, it will be unreferenced. Otherwise, it will be freed. 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()

void add_undo_method(callable: Callable) 🔗

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

void add_undo_property(object: Object, property: StringName, value: Variant) 🔗

Register a property that would change its value to value when the action is undone.

void add_undo_reference(object: Object) 🔗

Register a reference to an object that will be erased if the "undo" history is deleted. This is useful for objects added by the "undo" action and removed by the "do" action.

When the "undo" history is deleted, if the object is a RefCounted, it will be unreferenced. Otherwise, it will be freed. Do not use for resources.

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

void clear_history(increase_version: bool = 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.

void commit_action(execute: bool = 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.

void create_action(name: String, merge_mode: MergeMode = 0, backward_undo_ops: bool = false) 🔗

Create a new action. After this is called, do all your calls to add_do_method(), add_undo_method(), add_do_property(), and add_undo_property(), then commit the action with commit_action().

The way actions are merged is dictated by merge_mode.

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.

void end_force_keep_in_merge_ends() 🔗

Stops marking operations as to be processed even if the action gets merged with another in the MERGE_ENDS mode. See start_force_keep_in_merge_ends().

String get_action_name(id: int) 🔗

Gets the action name from its index.

int get_current_action() 🔗

Gets the index of the current action.

String get_current_action_name() const 🔗

Gets the name of the current action, equivalent to get_action_name(get_current_action()).

int get_history_count() 🔗

Renvoie combien d'éléments sont dans l'historique.

int get_version() const 🔗

Obtient la version. Chaque fois qu'une nouvelle action est engagée, le numéro de version du UndoRedo est augmenté automatiquement.

Ceci est surtout utile pour vérifier si quelque chose a changé par rapport à une version sauvegardée.

bool has_redo() const 🔗

Renvoie true si une action « refaire » (redo) est disponible.

bool has_undo() const 🔗

Renvoie true si une action « annuler » (undo) est disponible.

bool is_committing_action() const 🔗

Renvoie true si l'UndoRedo engage actuellement l'action, c'est-à-dire en exécutant sa méthode « faire » (do) ou son changement de propriété (voir commit_action()).

bool redo() 🔗

Redo the last action. Returns false if there was no action to redo.

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 MERGE_ENDS mode. Return to normal operation using end_force_keep_in_merge_ends().

bool undo() 🔗

Undo the last action. Returns false if there was no action to undo.