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

Eredita: Object

Fornisce un'interfaccia di alto livello per implementare le operazioni di annullamento e ripetizione.

Descrizione

UndoRedo funziona registrando metodi e modifiche di proprietà all'interno di "azioni". È possibile creare un'azione, quindi fornire modi per eseguire e annullare l'azione attraverso le chiamate di funzione e modifiche di proprietà, quindi confermare l'azione.

Quando un'azione è eseguita, tutti i metodi do_* saranno eseguiti. Se è usato il metodo undo(), i metodi undo_* saranno eseguiti. Se è usato il metodo redo(), ancora una volta, tutti i metodi do_* saranno eseguiti.

Ecco un esempio su come aggiungere un'azione:

var undo_redo = UndoRedo.new()

func do_something():
    pass # Inserisci qui il codice.

func undo_something():
    pass # Inserisci qui il codice che annulla quanto eseguito da "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()

private UndoRedo _undoRedo;

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

public void DoSomething()
{
    // Inserisci qui il codice.
}

public void UndoSomething()
{
    // Inserisci qui il codice che annulla quanto eseguito da "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();
}

Prima di chiamare uno qualsiasi dei metodi add_(un)do_*, bisogna prima chiamare create_action(). Dopodiché bisogna chiamare commit_action().

Se non c'è bisogno di registrare un metodo, è possibile omettere add_do_method() e add_undo_method(); lo stesso vale per le proprietà. È possibile anche registrare più di un metodo/proprietà.

Se stai creando un EditorPlugin e vuoi integrarlo nella cronologia degli annullamenti dell'editor, usa invece EditorUndoRedoManager.

Se stai registrando più proprietà/metodi che dipendono l'uno dall'altro, tieni presente che per impostazione predefinita le operazioni di annullamento sono chiamate nello stesso ordine in cui sono state aggiunte. Pertanto, invece di raggruppare le operazioni di ripetizione con le relative operazioni di annullamento, è meglio raggruppare le ripetizioni da un lato e gli annullamenti dall'altro come mostrato di seguito.

undo_redo.create_action("Add object")

# DO (Esegui/Ripeti)
undo_redo.add_do_method(_create_object)
undo_redo.add_do_method(_add_object_to_singleton)

# UNDO (Annulla)
undo_redo.add_undo_method(_remove_object_from_singleton)
undo_redo.add_undo_method(_destroy_that_object)

undo_redo.commit_action()

_undo_redo.CreateAction("Add object");

// DO (Esegui/Ripeti)
_undo_redo.AddDoMethod(new Callable(this, MethodName.CreateObject));
_undo_redo.AddDoMethod(new Callable(this, MethodName.AddObjectToSingleton));

// UNDO (Annulla)
_undo_redo.AddUndoMethod(new Callable(this, MethodName.RemoveObjectFromSingleton));
_undo_redo.AddUndoMethod(new Callable(this, MethodName.DestroyThatObject));

_undo_redo.CommitAction();

Proprietà

int

max_steps

0

Metodi

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

Segnali

version_changed() 🔗

Chiamato quando undo() o redo() sono stati chiamati.

Enumerazioni

enum MergeMode: 🔗

MergeMode MERGE_DISABLE = 0

Fa sì che le operazioni "do"/"undo" rimangano in azioni separate.

MergeMode MERGE_ENDS = 1

Unisce questa azione con quella precedente se hanno lo stesso nome. Mantiene solo le operazioni "undo" della prima azione e le operazioni "do" dell'ultima azione. Utile per modifiche sequenziali a un singolo valore.

MergeMode MERGE_ALL = 2

Unisce questa azione a quella precedente se hanno lo stesso nome.

Descrizioni delle proprietà

int max_steps = 0 🔗

void set_max_steps(value: int)
int get_max_steps()

Il numero massimo di passaggi che possono essere memorizzati nella cronologia di annullamento/ripetizione. Se il numero di passaggi memorizzati supera questo limite, i passaggi più vecchi sono rimossi dalla cronologia e non possono più essere raggiunti chiamando undo(). Un valore di 0 o inferiore significa nessun limite.

Descrizioni dei metodi

void add_do_method(callable: Callable) 🔗

Registra un Callable che sarà chiamato quando l'azione viene eseguita.

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

Registra una proprietà denominata property che cambierà il suo valore in value quando l'azione viene eseguita.

void add_do_reference(object: Object) 🔗

Registra un riferimento a un oggetto che sarà cancellato se la cronologia "do" viene eliminata. Questo è utile per gli oggetti aggiunti dall'azione "do" e rimossi dall'azione "undo".

Quando la cronologia "do" viene eliminata, se l'oggetto è un RefCounted, non verrà più referenziato. Altrimenti, verrà liberato. Non usarlo per le risorse.

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

Registra un Callable che verrà chiamato quando l'azione viene annullata.

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

Registra una proprietà denominata property che cambierà il suo valore in value quando l'azione viene annullata.

void add_undo_reference(object: Object) 🔗

Registra un riferimento a un oggetto che sarà cancellato se la cronologia "undo" viene eliminata. Questo è utile per gli oggetti aggiunti dall'azione "undo" e rimossi dall'azione "do".

Quando la cronologia "undo" viene eliminata, se l'oggetto è un RefCounted, non verrà più referenziato. Altrimenti, verrà liberato. Non usarlo per le risorse.

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

Cancella la cronologia annulla/ripeti e i riferimenti associati.

Passando false a increase_version si impedirà che il numero di versione aumenti quando la cronologia viene cancellata.

void commit_action(execute: bool = true) 🔗

Esegue l'azione. Se execute è true (che è di default), tutti i metodi/proprietà "do" vengono chiamati/impostati quando questa funzione viene chiamata.

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

Crea una nuova azione. Dopo che questa è stata chiamata, esegui tutte le chiamate a add_do_method(), add_undo_method(), add_do_property() e add_undo_property(), quindi compi l'azione con commit_action().

Il modo in cui le azioni sono unite è dettato da merge_mode.

Il modo in cui le operazioni di annullamento sono ordinate nelle azioni è dettato da backward_undo_ops. Quando backward_undo_ops è false le opzioni di annullamento sono ordinate nello stesso ordine in cui sono state aggiunte. Ciò significa che la prima operazione a essere aggiunta sarà la prima a essere annullata.

void end_force_keep_in_merge_ends() 🔗

Smette di contrassegnare le operazioni come da elaborare anche se l'azione viene unita a un'altra nella modalità MERGE_ENDS. Vedi start_force_keep_in_merge_ends().

String get_action_name(id: int) 🔗

Ottiene il nome dell'azione dal suo indice.

int get_current_action() 🔗

Ottiene l'indice dell'azione attuale.

String get_current_action_name() const 🔗

Ottiene il nome dell'azione attuale, equivalente a get_action_name(get_current_action()).

int get_history_count() 🔗

Restituisce quanti elementi sono presenti nella cronologia.

int get_version() const 🔗

Ottiene la versione. Ogni volta che viene compiuta una nuova azione, il numero di versione di UndoRedo viene incrementato automaticamente.

Questo è utile soprattutto per controllare se qualcosa è cambiato rispetto a una versione salvata.

bool has_redo() const 🔗

Restituisce true se un'azione "ripeti" è disponibile.

bool has_undo() const 🔗

Restituisce true se un'azione "annulla" è disponibile.

bool is_committing_action() const 🔗

Restituisce true se UndoRedo sta attualmente eseguendo l'azione, ovvero sta eseguendo il suo metodo "do" o la modifica della proprietà (vedi commit_action()).

bool redo() 🔗

Ripete l'ultima azione. Restituisce false se non c'era alcuna azione da ripetere.

void start_force_keep_in_merge_ends() 🔗

Contrassegna le prossime operazioni "do" e "undo" da elaborare anche se l'azione viene unita a un'altra nella modalità MERGE_ENDS. Ritorna al normale funzionamento usando end_force_keep_in_merge_ends().

bool undo() 🔗

Annulla l'ultima azione. Restituisce false se non c'era alcuna azione da annulla.