QUndoStack Class

Documentation des fonctions membres

[explicit] QUndoStack::QUndoStack(QObject *parent = nullptr)

Construit une pile d'annulation vide avec le parent parent. La pile sera initialement dans l'état "clean". Si parent est un objet QUndoGroup, la pile est automatiquement ajoutée au groupe.

Voir aussi push().

[virtual noexcept] QUndoStack::~QUndoStack()

Détruit la pile d'annulation, en supprimant toutes les commandes qui s'y trouvent. Si la pile se trouve dans un site QUndoGroup, elle est automatiquement supprimée du groupe.

Voir également QUndoStack().

void QUndoStack::beginMacro(const QString &text)

Commence la composition d'une macro-commande avec la description donnée text.

Une commande vide décrite par la description text est placée sur la pile. Toutes les commandes ultérieures placées sur la pile seront ajoutées aux enfants de la commande vide jusqu'à ce que endMacro() soit appelé.

Les appels à beginMacro() et endMacro() peuvent être imbriqués, mais chaque appel à beginMacro() doit avoir un appel correspondant à endMacro().

Pendant la composition d'une macro, la pile est désactivée. Cela signifie que :

• indexChanged() et cleanChanged() ne sont pas émis,
• canUndo() et canRedo() renvoient un message faux,
• l'appel à undo() ou redo() n'a aucun effet,
• les actions undo/redo sont désactivées.

La pile est activée et les signaux appropriés sont émis lorsque endMacro() est appelé pour la macro la plus externe.

stack.beginMacro("insert red text");
stack.push(new InsertText(document, idx, text));
stack.push(new SetColor(document, idx, text.length(), Qt::red));
stack.endMacro(); // indexChanged() is emitted

Ce code est équivalent à :

QUndoCommand *insertRed = new QUndoCommand(); // an empty command
insertRed->setText("insert red text");

new InsertText(document, idx, text, insertRed); // becomes child of insertRed
new SetColor(document, idx, text.length(), Qt::red, insertRed);

stack.push(insertRed);

Voir aussi endMacro().

bool QUndoStack::canRedo() const

Renvoie true si une commande est disponible pour être refaite ; sinon, renvoie false.

Cette fonction renvoie false si la pile est vide ou si la commande la plus élevée de la pile a déjà été refaite.

Synonyme de index() == count().

Voir également index() et canUndo().

[signal] void QUndoStack::canRedoChanged(bool canRedo)

Ce signal est émis lorsque la valeur de canRedo() change. Il est utilisé pour activer ou désactiver l'action de rétablissement renvoyée par createRedoAction(). canRedo spécifie la nouvelle valeur.

bool QUndoStack::canUndo() const

Renvoie true si une commande est disponible pour l'annulation ; sinon, renvoie false.

Cette fonction renvoie false si la pile est vide ou si la dernière commande de la pile a déjà été annulée.

Synonyme de index() == 0.

Voir également index() et canRedo().

[signal] void QUndoStack::canUndoChanged(bool canUndo)

Ce signal est émis lorsque la valeur de canUndo() change. Il est utilisé pour activer ou désactiver l'action d'annulation renvoyée par createUndoAction(). canUndo spécifie la nouvelle valeur.

[signal] void QUndoStack::cleanChanged(bool clean)

Ce signal est émis chaque fois que la pile entre ou quitte l'état de propreté. Si clean est vrai, la pile est dans un état propre ; sinon, ce signal indique qu'elle a quitté l'état propre.

Voir aussi isClean() et setClean().

int QUndoStack::cleanIndex() const

Renvoie l'index propre. Il s'agit de l'index auquel setClean() a été appelé.

Une pile peut ne pas avoir d'index propre. Cela se produit lorsqu'un document est enregistré, que certaines commandes sont annulées et qu'une nouvelle commande est passée. Comme push() supprime toutes les commandes annulées avant de pousser la nouvelle commande, la pile ne peut pas revenir à l'état propre. Dans ce cas, cette fonction renvoie -1. Le -1 peut également être renvoyé après un appel explicite à resetClean().

Voir aussi isClean() et setClean().

void QUndoStack::clear()

Efface la pile de commandes en supprimant toutes les commandes qui s'y trouvent, et ramène la pile à l'état initial.

Les commandes ne sont ni annulées ni refaites ; l'état de l'objet édité reste inchangé.

Cette fonction est généralement utilisée lorsque le contenu du document est abandonné.

Voir également QUndoStack().

const QUndoCommand *QUndoStack::command(int index) const

Renvoie un pointeur constant sur la commande à l'adresse index.

Cette fonction renvoie un pointeur constant, car la modification d'une commande, une fois qu'elle a été placée sur la pile et exécutée, entraîne presque toujours une corruption de l'état du document, si la commande est annulée ou refaite ultérieurement.

Voir aussi QUndoCommand::child().

int QUndoStack::count() const

Renvoie le nombre de commandes sur la pile. Les macro-commandes sont comptées comme une seule commande.

Voir aussi index(), setIndex() et command().

QAction *QUndoStack::createRedoAction(QObject *parent, const QString &prefix = QString()) const

Crée un objet redo QAction avec l'adresse parent donnée.

Le déclenchement de cette action entraînera un appel à redo(). Le texte de cette action est le texte de la commande qui sera refaite lors du prochain appel à redo(), préfixé par le prefix spécifié. Si aucune commande n'est disponible pour être refaite, cette action sera désactivée.

Si prefix est vide, le modèle par défaut "Redo %1" est utilisé à la place du préfixe. Avant Qt 4.8, le préfixe "Redo" était utilisé par défaut.

Voir aussi createUndoAction(), canRedo(), et QUndoCommand::text().

QAction *QUndoStack::createUndoAction(QObject *parent, const QString &prefix = QString()) const

Crée un objet d'annulation QAction avec l'adresse parent.

Le déclenchement de cette action entraînera un appel à undo(). Le texte de cette action est le texte de la commande qui sera annulée lors du prochain appel à undo(), préfixé par le prefix spécifié. Si aucune commande n'est disponible pour l'annulation, cette action sera désactivée.

Si prefix est vide, le modèle par défaut "Undo %1" est utilisé à la place du préfixe. Avant Qt 4.8, le préfixe "Undo" était utilisé par défaut.

Voir aussi createRedoAction(), canUndo() et QUndoCommand::text().

void QUndoStack::endMacro()

Termine la composition d'une macro-commande.

S'il s'agit de la macro la plus externe d'un ensemble de macros imbriquées, cette fonction émet indexChanged() une fois pour l'ensemble de la macro-commande.

Voir aussi beginMacro().

int QUndoStack::index() const

Renvoie l'index de la commande en cours. Il s'agit de la commande qui sera exécutée lors du prochain appel à redo(). Il ne s'agit pas toujours de la commande la plus élevée sur la pile, car un certain nombre de commandes peuvent avoir été annulées.

Voir aussi setIndex(), undo(), redo() et count().

[signal] void QUndoStack::indexChanged(int idx)

Ce signal est émis lorsqu'une commande modifie l'état du document. Cela se produit lorsqu'une commande est annulée ou refaite. Lorsqu'une macro-commande est annulée ou refaite, ou que setIndex() est appelé, ce signal n'est émis qu'une seule fois.

idx spécifie l'index de la commande courante, c'est-à-dire la commande qui sera exécutée lors du prochain appel à redo().

Voir également index() et setIndex().

bool QUndoStack::isClean() const

Si la pile est dans un état propre, elle renvoie true; sinon, elle renvoie false.

Voir aussi setClean() et cleanIndex().

void QUndoStack::push(QUndoCommand *cmd)

Repousse cmd sur la pile ou le fusionne avec la dernière commande exécutée. Dans les deux cas, il exécute cmd en appelant sa fonction redo().

Si l'id de cmd n'est pas -1 et si l'id est le même que celui de la dernière commande exécutée, QUndoStack tentera de fusionner les deux commandes en appelant QUndoCommand::mergeWith() sur la dernière commande exécutée. Si QUndoCommand::mergeWith() renvoie true, cmd est supprimé.

Après avoir appelé QUndoCommand::redo() et, le cas échéant, QUndoCommand::mergeWith(), QUndoCommand::isObsolete() sera appelé pour cmd ou la commande fusionnée. Si QUndoCommand::isObsolete() renvoie true, alors cmd ou la commande fusionnée sera supprimée de la pile.

Dans tous les autres cas, cmd est simplement poussé sur la pile.

Si des commandes ont été annulées avant que cmd ne soit poussé, la commande en cours et toutes les commandes au-dessus d'elle sont supprimées. C'est pourquoi cmd finit toujours par être la commande la plus élevée de la pile.

Une fois qu'une commande est poussée, la pile en prend possession. Il n'y a pas de getters pour retourner la commande, car la modifier après qu'elle a été exécutée entraînera presque toujours une corruption de l'état du document.

Voir également QUndoCommand::id() et QUndoCommand::mergeWith().

[slot] void QUndoStack::redo()

Refait la commande en cours en appelant QUndoCommand::redo(). Incrémente l'index de la commande en cours.

Si la pile est vide ou si la première commande de la pile a déjà été refaite, cette fonction ne fait rien.

Si QUndoCommand::isObsolete() renvoie un résultat positif pour la commande en cours, celle-ci sera supprimée de la pile. De plus, si l'index de nettoyage est supérieur ou égal à l'index de la commande en cours, l'index de nettoyage est réinitialisé.

Voir également undo() et index().

QString QUndoStack::redoText() const

Renvoie le texte de la commande qui sera refaite lors du prochain appel à redo().

Voir aussi QUndoCommand::actionText() et undoText().

[signal] void QUndoStack::redoTextChanged(const QString &redoText)

Ce signal est émis lorsque la valeur de redoText() change. Il est utilisé pour mettre à jour la propriété text de l'action redo renvoyée par createRedoAction(). redoText spécifie le nouveau texte.

[slot] void QUndoStack::resetClean()

Quitte l'état de propreté et émet cleanChanged() si la pile était propre. Cette méthode réinitialise l'index de nettoyage à -1.

Elle est généralement appelée dans les cas suivants, lorsqu'un document a été :

• créé sur la base d'un modèle et n'a pas été sauvegardé, de sorte qu'aucun nom de fichier n'a encore été associé au document.
• restauré à partir d'un fichier de sauvegarde
• a été modifié en dehors de l'éditeur et que l'utilisateur ne l'a pas rechargé.

Voir aussi isClean(), setClean(), et cleanIndex().

[slot] void QUndoStack::setClean()

Marque la pile comme étant propre et émet cleanChanged() si la pile n'était pas déjà propre.

Ce signal est généralement émis lors de l'enregistrement d'un document, par exemple.

Chaque fois que la pile revient à cet état par l'utilisation des commandes undo/redo, elle émet le signal cleanChanged(). Ce signal est également émis lorsque la pile quitte l'état "clean".

Voir également isClean(), resetClean() et cleanIndex().

[slot] void QUndoStack::setIndex(int idx)

Appelle à plusieurs reprises undo() ou redo() jusqu'à ce que l'index de la commande en cours atteigne idx. Cette fonction peut être utilisée pour faire avancer ou reculer l'état du document. indexChanged() n'est émis qu'une seule fois.

Voir également index(), count(), undo() et redo().

QString QUndoStack::text(int idx) const

Renvoie le texte de la commande à l'index idx.

Voir aussi beginMacro().

[slot] void QUndoStack::undo()

Annule la commande située en dessous de la commande actuelle en appelant QUndoCommand::undo(). Diminue l'index de la commande en cours.

Si la pile est vide ou si la commande du bas de la pile a déjà été annulée, cette fonction ne fait rien.

Une fois la commande annulée, si QUndoCommand::isObsolete() renvoie true, la commande sera supprimée de la pile. En outre, si l'indice de nettoyage est supérieur ou égal à l'indice de la commande en cours, l'indice de nettoyage est réinitialisé.

Voir également redo() et index().

QString QUndoStack::undoText() const

Renvoie le texte de la commande qui sera annulée lors du prochain appel à undo().

Voir également QUndoCommand::actionText() et redoText().

[signal] void QUndoStack::undoTextChanged(const QString &undoText)

Ce signal est émis lorsque la valeur de undoText() change. Il est utilisé pour mettre à jour la propriété text de l'action d'annulation renvoyée par createUndoAction(). undoText spécifie le nouveau texte.