QUndoStack Class

Documentation des fonctions membres

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

Crée une pile d'annulation vide avec l'parent parent. La pile sera initialement à l'état « clean ». Si parent est un objet QUndoGroup, la pile est automatiquement ajoutée au groupe.

Voir également push().

[virtual noexcept] QUndoStack::~QUndoStack()

Supprime la pile d'annulation, en effaçant toutes les commandes qu'elle contient. Si la pile se trouve dans un « QUndoGroup », elle est automatiquement retirée de ce groupe.

Voir aussi QUndoStack().

void QUndoStack::beginMacro(const QString &text)

Lance la création d'une commande macro avec la description d'text s fournie.

Une commande vide décrite par l’ text spécifiée est placée sur la pile. Toutes les commandes suivantes placées sur la pile seront ajoutées aux enfants de la commande vide jusqu’à ce que la fonction endMacro() soit appelée.

Les appels à `beginMacro()` et ` endMacro()` peuvent être imbriqués, mais chaque appel à `beginMacro()` doit être suivi d’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 émises,
• canUndo() et canRedo() renvoient « false »,
• l'appel à ` undo()` ou ` redo()` n'a aucun effet,
• les actions d’annulation et de rétablissement sont désactivées.

La pile est réactivée et les signaux appropriés sont émis lorsque la fonction ` endMacro()` est appelée 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 » s'il existe une commande pouvant être refaite ; sinon, renvoie « false ».

Cette fonction renvoie « false » si la pile est vide ou si la commande située en haut de la pile a déjà été réitérée.

Synonyme de ` index()` == ` count()`.

Voir également index() et canUndo().

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

Ce signal est émis chaque fois que la valeur de ` canRedo()` change. Il sert à activer ou désactiver l'action de réexécution renvoyée par ` createRedoAction()`. ` canRedo ` spécifie la nouvelle valeur.

bool QUndoStack::canUndo() const

Renvoie « true » s'il existe une commande pouvant être annulée ; sinon, renvoie « false ».

Cette fonction renvoie false si la pile est vide ou si la commande située au bas 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 chaque fois que la valeur de ` canUndo()` change. Il sert à 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 dans l'état « propre » ou en sort. Si la propriété clean est vraie, la pile est dans un état « propre » ; dans le cas contraire, ce signal indique qu'elle a quitté cet état.

Voir également isClean() et setClean().

int QUndoStack::cleanIndex() const

Renvoie l’index « propre ». Il s’agit de l’index auquel la fonction setClean() a été appelée.

Une pile peut ne pas avoir d'index « propre ». Cela se produit si un document est enregistré, que certaines commandes sont annulées, puis qu'une nouvelle commande est ajoutée à la pile. Étant donné que la fonction push() supprime toutes les commandes annulées avant d'ajouter la nouvelle commande, la pile ne peut plus revenir à son état « propre ». Dans ce cas, cette fonction renvoie -1. La valeur -1 peut également être renvoyée après un appel explicite à resetClean().

Voir également ` isClean()` et ` setClean()`.

void QUndoStack::clear()

Efface la pile de commandes en supprimant toutes les commandes qu'elle contient, et ramène la pile à son état initial.

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

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

Voir aussi QUndoStack().

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

Renvoie un pointeur const vers la commande à l'adresse index.

Cette fonction renvoie un pointeur const, 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 ensuite annulée ou rétablie.

Voir également QUndoCommand::child().

int QUndoStack::count() const

Renvoie le nombre de commandes présentes dans la pile. Les commandes macro sont comptées comme une seule commande.

Voir également index(), setIndex() et command().

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

Crée un objet « redo » de type « QAction » avec l'parent spécifiée.

Le déclenchement de cette action entraînera l'appel de la fonction redo(). Le texte de cette action correspond au texte de la commande qui sera réitérée lors du prochain appel à redo(), préfixé par le préfixe spécifié prefix. S'il n'y a aucune commande disponible à réitérer, cette action sera désactivée.

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

Voir également createUndoAction(), canRedo() et QUndoCommand::text().

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

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

Le déclenchement de cette action entraînera l'appel de la fonction undo(). Le texte de cette action correspond au texte de la commande qui sera annulée lors du prochain appel de undo(), précédé du préfixe spécifié prefix. S'il n'y a aucune commande disponible à annuler, 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 également createRedoAction(), canUndo() et QUndoCommand::text().

void QUndoStack::endMacro()

Mette fin à la composition d'une commande macro.

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

Voir également beginMacro().

int QUndoStack::index() const

Renvoie l'index de la commande actuelle. Il s'agit de la commande qui sera exécutée lors du prochain appel à la fonction redo(). Ce n'est pas toujours la commande située tout en haut de la pile, car certaines commandes ont pu être annulées.

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

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

Ce signal est émis chaque fois qu’une commande modifie l’état du document. Cela se produit lorsqu’une commande est annulée ou rétablie. Lorsqu’une commande de macro est annulée ou rétablie, ou lorsque la fonction ` setIndex()` est appelée, ce signal n’est émis qu’une seule fois.

idx Spécifie l'index de la commande actuelle, 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 à l'état « clean », renvoie true; sinon, renvoie false.

Voir également setClean() et cleanIndex().

void QUndoStack::push(QUndoCommand *cmd)

Ajoute cmd à la pile ou la fusionne avec la commande exécutée le plus récemment. Dans les deux cas, exécute cmd en appelant sa fonction redo().

Si l’identifiant de ` cmd` n’est pas -1, et si cet identifiant est identique à celui de la commande exécutée en dernier, ` QUndoStack ` tentera de fusionner les deux commandes en appelant ` QUndoCommand::mergeWith()` sur la commande exécutée en dernier. 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 ajouté à la pile.

Si des commandes ont été annulées avant que cmd ne soit poussée, la commande actuelle et toutes les commandes situées au-dessus d’elle sont supprimées. Par conséquent, cmd se retrouve toujours en tête de la pile.

Une fois qu’une commande est placée sur la pile, celle-ci en prend possession. Il n’existe pas de méthode d’accès permettant de récupérer la commande, car la modifier après son exécution entraînerait presque toujours une corruption de l’état du document.

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

[slot] void QUndoStack::redo()

Répète la commande actuelle en appelant la fonction ` QUndoCommand::redo()`. Incrémente l'index de la commande actuelle.

Si la pile est vide, ou si la commande située en haut de la pile a déjà été réitérée, cette fonction ne fait rien.

Si la fonction ` QUndoCommand::isObsolete()` renvoie `true` pour la commande en cours, celle-ci est 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 réitérée lors du prochain appel à la fonction ` redo()`.

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

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

Ce signal est émis chaque fois que la valeur de ` redoText()` change. Il sert à mettre à jour la propriété « text » de l'action de rétablissement renvoyée par ` createRedoAction()`. ` redoText ` spécifie le nouveau texte.

[slot] void QUndoStack::resetClean()

Quitte l'état « clean » et renvoie ` cleanChanged()` si la pile était « clean ». Cette méthode réinitialise l'index « clean » à -1.

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

• créé à partir d'un modèle et n'a pas encore été enregistré, de sorte qu'aucun nom de fichier ne lui a encore été attribué ;
• restauré à partir d’un fichier de sauvegarde ;
• modifié en dehors de l'éditeur et que l'utilisateur ne l'a pas rechargé.

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

[slot] void QUndoStack::setClean()

Marque la pile comme étant « propre » et appelle la fonction ` cleanChanged()` si la pile ne l'était pas déjà.

Cette fonction est généralement appelée lors de l'enregistrement d'un document, par exemple.

Chaque fois que la pile revient à cet état à la suite de l’utilisation des commandes « Annuler »/« Rétablir », elle émet le signal cleanChanged(). Ce signal est également émis lorsque la pile quitte l’état « propre ».

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

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

Appelle de manière répétée undo() ou redo() jusqu’à ce que l’index de commande actuel atteigne idx. Cette fonction peut être utilisée pour faire défiler l’état du document vers l’avant ou vers l’arrière. indexChanged() n’est émise 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 juste en dessous de la commande actuelle en appelant la fonction ` QUndoCommand::undo()`. Décrémente l'index de la commande actuelle.

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

Une fois la commande annulée, si la fonction ` QUndoCommand::isObsolete()` renvoie ` true`, la commande est supprimée de la pile. De plus, si l’index de nettoyage est supérieur ou égal à l’index de la commande actuelle, l’index 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 à la fonction ` undo()`.

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

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

Ce signal est émis chaque fois que la valeur de ` undoText()` change. Il sert à mettre à jour la propriété « text » de l'action d'annulation renvoyée par ` createUndoAction()`. ` undoText ` spécifie le nouveau texte.