QUndoStack Class

Documentación de las funciones miembro

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

Construye una pila de deshacer vacía con el padre parent. La pila estará inicialmente en estado limpio. Si parent es un objeto QUndoGroup, la pila se añade automáticamente al grupo.

Véase también push().

[virtual noexcept] QUndoStack::~QUndoStack()

Destruye la pila de deshacer, borrando cualquier orden que se encuentre en ella. Si la pila está en QUndoGroup, la pila se elimina automáticamente del grupo.

Véase también QUndoStack().

void QUndoStack::beginMacro(const QString &text)

Inicia la composición de un macrocomando con la descripción dada en text.

Se coloca en la pila un comando vacío descrito por el text especificado. Cualquier comando posterior que se introduzca en la pila se añadirá a los hijos del comando vacío hasta que se llame a endMacro().

Las llamadas a beginMacro() y endMacro() pueden estar anidadas, pero cada llamada a beginMacro() debe tener una llamada a endMacro().

Mientras se compone una macro, la pila está desactivada. Esto significa que:

• indexChanged() y cleanChanged() no se emiten,
• canUndo() y canRedo() devuelven false,
• llamar a undo() o redo() no tiene ningún efecto,
• las acciones deshacer/rehacer están deshabilitadas.

La pila se habilita y se emiten las señales apropiadas cuando se llama a endMacro() para la macro más externa.

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

Este código es equivalente a:

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

Véase también endMacro().

bool QUndoStack::canRedo() const

Devuelve true si hay una orden disponible para rehacer; en caso contrario devuelve false.

Esta función devuelve false si la pila está vacía o si el comando superior de la pila ya ha sido rehecho.

Sinónimo de index() == count().

Véase también index() y canUndo().

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

Esta señal se emite cada vez que cambia el valor de canRedo(). Se utiliza para activar o desactivar la acción de rehacer devuelta por createRedoAction(). canRedo especifica el nuevo valor.

bool QUndoStack::canUndo() const

Devuelve true si hay una orden disponible para deshacer; en caso contrario devuelve false.

Esta función devuelve false si la pila está vacía, o si el comando inferior de la pila ya ha sido deshecho.

Sinónimo de index() == 0.

Véase también index() y canRedo().

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

Esta señal se emite cada vez que cambia el valor de canUndo(). Se utiliza para activar o desactivar la acción de deshacer devuelta por createUndoAction(). canUndo especifica el nuevo valor.

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

Esta señal se emite cada vez que la pila entra o sale del estado limpio. Si clean es verdadero, la pila está en estado limpio; en caso contrario, esta señal indica que ha salido del estado limpio.

Véase también isClean() y setClean().

int QUndoStack::cleanIndex() const

Devuelve el índice limpio. Es el índice en el que se llamó a setClean().

Una pila puede no tener un índice limpio. Esto ocurre si se guarda un documento, se deshacen algunos comandos y luego se introduce un nuevo comando. Dado que push() borra todos los comandos deshechos antes de introducir el nuevo comando, la pila no puede volver al estado limpio de nuevo. En este caso, esta función devuelve -1. El -1 también puede ser devuelto después de una llamada explícita a resetClean().

Véase también isClean() y setClean().

void QUndoStack::clear()

Borra la pila de comandos eliminando todos los comandos que contiene y devuelve la pila al estado limpio.

Los comandos no se deshacen ni se rehacen; el estado del objeto editado permanece inalterado.

Esta función suele utilizarse cuando se abandona el contenido del documento.

Véase también QUndoStack().

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

Devuelve un puntero constante a la orden en index.

Esta función devuelve un puntero constante, porque la modificación de un comando, una vez que ha sido introducido en la pila y ejecutado, casi siempre causa la corrupción del estado del documento, si el comando se deshace o rehace más tarde.

Véase también QUndoCommand::child().

int QUndoStack::count() const

Devuelve el número de comandos en la pila. Los macrocomandos se cuentan como un comando.

Véase también index(), setIndex() y command().

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

Crea un objeto redo QAction con el valor dado parent.

La activación de esta acción provocará una llamada a redo(). El texto de esta acción es el texto del comando que se rehará en la siguiente llamada a redo(), prefijado por el prefix especificado. Si no hay ninguna orden disponible para rehacer, esta acción se desactivará.

Si prefix está vacío, se utilizará la plantilla por defecto "Redo %1" en lugar del prefijo. Antes de Qt 4.8, se utilizaba por defecto el prefijo "Redo".

Véase también createUndoAction(), canRedo(), y QUndoCommand::text().

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

Crea un objeto deshacer QAction con el valor dado parent.

La activación de esta acción provocará una llamada a undo(). El texto de esta acción es el texto del comando que se deshará en la siguiente llamada a undo(), prefijado por el prefix especificado. Si no hay ninguna orden disponible para deshacer, esta acción se desactivará.

Si prefix está vacío, se utilizará la plantilla por defecto "Deshacer %1" en lugar del prefijo. Antes de Qt 4.8, se utilizaba por defecto el prefijo "Deshacer".

Véase también createRedoAction(), canUndo(), y QUndoCommand::text().

void QUndoStack::endMacro()

Finaliza la composición de un macrocomando.

Si ésta es la macro más externa de un conjunto de macros anidadas, esta función emite indexChanged() una vez para todo el macrocomando.

Véase también beginMacro().

int QUndoStack::index() const

Devuelve el índice del comando actual. Este es el comando que se ejecutará en la siguiente llamada a redo(). No siempre es la orden más alta de la pila, ya que pueden haberse deshecho varias órdenes.

Véase también setIndex(), undo(), redo() y count().

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

Esta señal se emite cada vez que un comando modifica el estado del documento. Esto ocurre cuando se deshace o rehace un comando. Cuando se deshace o rehace un macrocomando, o se llama a setIndex(), esta señal sólo se emite una vez.

idx especifica el índice del comando actual, es decir, el comando que se ejecutará en la siguiente llamada a redo().

Véase también index() y setIndex().

bool QUndoStack::isClean() const

Si la pila está en estado limpio, devuelve true; en caso contrario devuelve false.

Véase también setClean() y cleanIndex().

void QUndoStack::push(QUndoCommand *cmd)

Coloca cmd en la pila o lo combina con el comando ejecutado más recientemente. En cualquier caso, ejecuta cmd llamando a su función redo().

Si el id de cmd no es -1, y si el id es el mismo que el del comando ejecutado más recientemente, QUndoStack intentará fusionar los dos comandos llamando a QUndoCommand::mergeWith() en el comando ejecutado más recientemente. Si QUndoCommand::mergeWith() devuelve true, se elimina cmd.

Después de llamar a QUndoCommand::redo() y, si corresponde, a QUndoCommand::mergeWith(), se llamará a QUndoCommand::isObsolete() para cmd o el comando fusionado. Si QUndoCommand::isObsolete() devuelve true, entonces cmd o el comando fusionado serán borrados de la pila.

En todos los demás casos, cmd simplemente se coloca en la pila.

Si los comandos se deshicieron antes de que cmd fuera empujado, el comando actual y todos los comandos por encima de él se eliminan. Por lo tanto, cmd siempre termina siendo el primero de la pila.

Una vez que se ha introducido una orden, la pila toma posesión de ella. No hay getters para devolver el comando, ya que modificarlo después de que se haya ejecutado casi siempre provocará la corrupción del estado del documento.

Véase también QUndoCommand::id() y QUndoCommand::mergeWith().

[slot] void QUndoStack::redo()

Rehace el comando actual llamando a QUndoCommand::redo(). Incrementa el índice del comando actual.

Si la pila está vacía, o si el comando superior de la pila ya ha sido rehecho, esta función no hace nada.

Si QUndoCommand::isObsolete() devuelve verdadero para el comando actual, entonces el comando será borrado de la pila. Además, si el índice de limpieza es mayor o igual que el índice del comando actual, entonces se restablece el índice de limpieza.

Véase también undo() y index().

QString QUndoStack::redoText() const

Devuelve el texto del comando que será rehecho en la próxima llamada a redo().

Véase también QUndoCommand::actionText() y undoText().

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

Esta señal se emite cada vez que cambia el valor de redoText(). Se utiliza para actualizar la propiedad text de la acción de rehacer devuelta por createRedoAction(). redoText especifica el nuevo texto.

[slot] void QUndoStack::resetClean()

Deja el estado limpio y emite cleanChanged() si la pila estaba limpia. Este método restablece el índice clean a -1.

Esto se llama típicamente en los siguientes casos, cuando un documento ha sido:

• creado basándose en alguna plantilla y no se ha guardado, por lo que aún no se ha asociado ningún nombre de archivo al documento.
• restaurado desde un archivo de copia de seguridad.
• modificado fuera del editor y el usuario no lo ha vuelto a cargar.

Véase también isClean(), setClean(), y cleanIndex().

[slot] void QUndoStack::setClean()

Marca la pila como limpia y emite cleanChanged() si la pila no estaba ya limpia.

Esto se hace normalmente cuando se guarda un documento, por ejemplo.

Cada vez que la pila vuelve a este estado mediante el uso de comandos de deshacer/rehacer, emite la señal cleanChanged(). Esta señal también se emite cuando la pila abandona el estado limpio.

Véase también isClean(), resetClean() y cleanIndex().

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

Llama repetidamente a undo() o redo() hasta que el índice del comando actual alcanza idx. Esta función puede utilizarse para hacer avanzar o retroceder el estado del documento. indexChanged() sólo se emite una vez.

Véase también index(), count(), undo() y redo().

QString QUndoStack::text(int idx) const

Devuelve el texto del comando en el índice idx.

Véase también beginMacro().

[slot] void QUndoStack::undo()

Deshace el comando por debajo del comando actual llamando a QUndoCommand::undo(). Disminuye el índice del comando actual.

Si la pila está vacía, o si el comando inferior de la pila ya se ha deshecho, esta función no hace nada.

Después de deshacer el comando, si QUndoCommand::isObsolete() devuelve true, entonces el comando se borrará de la pila. Además, si el índice limpio es mayor o igual que el índice del comando actual, entonces se restablece el índice limpio.

Véase también redo() y index().

QString QUndoStack::undoText() const

Devuelve el texto del comando que será deshecho en la próxima llamada a undo().

Véase también QUndoCommand::actionText() y redoText().

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

Esta señal se emite cada vez que cambia el valor de undoText(). Se utiliza para actualizar la propiedad text de la acción de deshacer devuelta por createUndoAction(). undoText especifica el nuevo texto.