En esta página

QUndoStack Class

La clase QUndoStack es una pila de objetos ` QUndoCommand `. Más información...

Encabezado: #include <QUndoStack>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Heredado de: QObject

Propiedades

Funciones públicas

QUndoStack(QObject *parent = nullptr)
virtual ~QUndoStack()
void beginMacro(const QString &text)
bool canRedo() const
bool canUndo() const
int cleanIndex() const
void clear()
const QUndoCommand *command(int index) const
int count() const
QAction *createRedoAction(QObject *parent, const QString &prefix = QString()) const
QAction *createUndoAction(QObject *parent, const QString &prefix = QString()) const
void endMacro()
int index() const
bool isActive() const
bool isClean() const
void push(QUndoCommand *cmd)
QString redoText() const
void setUndoLimit(int limit)
QString text(int idx) const
int undoLimit() const
QString undoText() const

Ranuras públicas

void redo()
void resetClean()
void setActive(bool active = true)
void setClean()
void setIndex(int idx)
void undo()

Señales

void canRedoChanged(bool canRedo)
void canUndoChanged(bool canUndo)
void cleanChanged(bool clean)
void indexChanged(int idx)
void redoTextChanged(const QString &redoText)
void undoTextChanged(const QString &undoText)

Descripción detallada

Para obtener una visión general del marco de trabajo «Undo» de Qt, consulta el documento de introducción.

Una pila de deshacer mantiene una pila de comandos que se han aplicado a un documento.

Los nuevos comandos se añaden a la pila mediante push(). Los comandos se pueden deshacer y rehacer utilizando undo() y redo(), o bien activando las acciones devueltas por createUndoAction() y createRedoAction().

QUndoStack realiza un seguimiento del comando current. Este es el comando que se ejecutará en la siguiente llamada a redo(). El índice de este comando lo devuelve index(). El estado del objeto editado se puede avanzar o retroceder mediante ` setIndex()`. Si el comando situado en la parte superior de la pila ya se ha rehacer, ` index()` es igual a ` count()`.

QUndoStack ofrece soporte para acciones de deshacer y rehacer, compresión de comandos, macros de comandos y admite el concepto de estado limpio.

Acciones de deshacer y rehacer

QUndoStack proporciona prácticos objetos de deshacer y rehacer QAction, que pueden insertarse en un menú o en una barra de herramientas. Cuando se deshacen o se rehacen comandos, QUndoStack actualiza las propiedades de texto de estas acciones para reflejar el cambio que provocarán. Las acciones también se desactivan cuando no hay ningún comando disponible para deshacer o rehacer. Estas acciones se obtienen mediante las funciones ` QUndoStack::createUndoAction()` y ` QUndoStack::createRedoAction()`.

Compresión de comandos y macros

La compresión de comandos resulta útil cuando varios comandos pueden comprimirse en un único comando que puede deshacerse y rehacerse en una sola operación. Por ejemplo, cuando un usuario escribe un carácter en un editor de texto, se crea un nuevo comando. Este comando inserta el carácter en el documento en la posición del cursor. Sin embargo, resulta más cómodo para el usuario poder deshacer o rehacer la introducción de palabras completas, frases o párrafos. La compresión de comandos permite fusionar estos comandos de un solo carácter en un único comando que inserta o elimina secciones de texto. Para obtener más información, consulte QUndoCommand::mergeWith() y push().

Una macro de comando es una secuencia de comandos, todos los cuales se deshacen y se rehacen de una sola vez. Las macros de comando se crean asignando a un comando una lista de comandos secundarios. Al deshacer o rehacer el comando principal, se desharán o rehacerán los comandos secundarios. Las macros de comando pueden crearse explícitamente especificando un comando principal en el constructor QUndoCommand, o utilizando las funciones de conveniencia beginMacro() y endMacro().

Aunque la compresión de comandos y las macros parecen tener el mismo efecto para el usuario, a menudo tienen usos diferentes en una aplicación. Los comandos que realizan pequeños cambios en un documento pueden comprimirse de forma útil si no es necesario registrarlos individualmente y si solo los cambios más importantes son relevantes para el usuario. Sin embargo, en el caso de los comandos que deben registrarse individualmente, o aquellos que no pueden comprimirse, resulta útil emplear macros para ofrecer una experiencia de usuario más cómoda, al tiempo que se mantiene un registro de cada comando.

Estado limpio

QUndoStack admite el concepto de «estado limpio». Cuando el documento se guarda en el disco, la pila puede marcarse como limpia mediante la función setClean(). Cada vez que la pila vuelve a este estado mediante los comandos de deshacer y rehacer, emite la señal cleanChanged(). Esta señal también se emite cuando la pila sale del estado limpio. Esta señal se suele utilizar para activar y desactivar las acciones de guardado en la aplicación, y para actualizar el título del documento a fin de reflejar que contiene cambios sin guardar.

Comandos obsoletos

QUndoStack puede eliminar comandos de la pila si ya no son necesarios. Un ejemplo podría ser eliminar un comando cuando dos comandos se fusionan de tal manera que el comando fusionado carece de función. Esto se puede observar con los comandos de desplazamiento, en los que el usuario mueve el ratón a una parte de la pantalla y luego lo vuelve a la posición original. El comando fusionado da como resultado un movimiento del ratón de 0. Este comando puede eliminarse, ya que no tiene ninguna utilidad. Otro ejemplo son los comandos de red que fallan debido a problemas de conexión. En este caso, el comando debe eliminarse de la pila porque las funciones ` redo()` y ` undo()` no tienen ninguna utilidad, ya que hubo problemas de conexión.

Un comando puede marcarse como obsoleto mediante la función QUndoCommand::setObsolete(). El indicador QUndoCommand::isObsolete() se comprueba en QUndoStack::push(), QUndoStack::undo(), QUndoStack::redo() y QUndoStack::setIndex() tras llamar a QUndoCommand::undo(), QUndoCommand::redo() y QUndoCommand:mergeWith(), cuando proceda.

Si un comando se marca como obsoleto y el índice de limpieza es mayor o igual que el índice actual del comando, el índice de limpieza se restablecerá cuando el comando se elimine de la pila.

Véase también QUndoCommand y QUndoView.

Documentación de propiedades

active : bool

Esta propiedad indica el estado activo de esta pila.

Una aplicación suele tener varias pilas de deshacer, una por cada documento abierto. La pila activa es aquella asociada al documento actualmente activo. Si la pila pertenece a un « QUndoGroup », las llamadas a « QUndoGroup::undo()» o « QUndoGroup::redo()» se reenviarán a esta pila cuando esté activa. Si la pila de deshacer ( QUndoGroup ) está supervisada por una vista de pila ( QUndoView), la vista mostrará el contenido de esta pila cuando esté activa. Si la pila no pertenece a una vista de pila ( QUndoGroup), activarla no tendrá ningún efecto.

Es responsabilidad del programador especificar qué pila está activa llamando a setActive(), normalmente cuando la ventana del documento asociada recibe el foco.

Funciones de acceso:

bool isActive() const
void setActive(bool active = true)

Véase también « QUndoGroup ».

[read-only] canRedo : bool

Esta propiedad indica si esta pila admite la acción «Rehacer».

Esta propiedad indica si hay o no un comando que se pueda deshacer.

Funciones de acceso:

bool canRedo() const

Señal de notificación:

void canRedoChanged(bool canRedo)

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

[read-only] canUndo : bool

Esta propiedad indica si se pueden deshacer las acciones de esta pila.

Esta propiedad indica si hay o no un comando que se pueda deshacer.

Funciones de acceso:

bool canUndo() const

Señal de notificación:

void canUndoChanged(bool canUndo)

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

[read-only] clean : bool

Esta propiedad indica el estado de limpieza de esta pila.

Esta propiedad indica si la pila está limpia o no. Por ejemplo, una pila está limpia cuando se ha guardado un documento.

Funciones de acceso:

bool isClean() const

Señal de notificación:

void cleanChanged(bool clean)

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

[read-only] redoText : QString

Esta propiedad contiene el texto del comando que se va a repetir en la siguiente llamada a `xml-ph-0000@deepl.internal()`.

Esta propiedad contiene el texto del comando que se volverá a ejecutar en la próxima llamada a ` redo()`.

Funciones de acceso:

QString redoText() const

Señal de notificación:

void redoTextChanged(const QString &redoText)

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

undoLimit : int

Esta propiedad establece el número máximo de comandos que puede contener esta pila.

Cuando el número de comandos de una pila supera el valor de undoLimit de la pila, los comandos se eliminan desde la parte inferior de la pila. Los comandos de macro (comandos con comandos secundarios) se tratan como un solo comando. El valor por defecto es 0, lo que significa que no hay límite.

Esta propiedad solo se puede establecer cuando la pila de deshacer está vacía, ya que establecerla en una pila que no esté vacía podría eliminar el comando situado en el índice actual. Al llamar a setUndoLimit() en una pila que no esté vacía, se muestra una advertencia y no se realiza ninguna acción.

Funciones de acceso:

int undoLimit() const
void setUndoLimit(int limit)

[read-only] undoText : QString

Esta propiedad contiene el texto del siguiente comando que se va a deshacer.

Esta propiedad contiene el texto del comando que se deshará en la próxima llamada a ` undo()`.

Funciones de acceso:

QString undoText() const

Señal de notificación:

void undoTextChanged(const QString &undoText)

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

Documentación de las funciones miembro

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

Crea una pila de deshacer vacía con el objeto padre ` parent`. La pila se encontrará 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()

Elimina la pila de deshacer, borrando todos los comandos que contenga. Si la pila se encuentra en un grupo de trabajo ( QUndoGroup), se elimina automáticamente de dicho grupo.

Véase también QUndoStack().

void QUndoStack::beginMacro(const QString &text)

Inicia la composición de un comando macro con la descripción de « text » indicada.

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

Las llamadas a `beginMacro()` y ` endMacro()` pueden anidarse, pero cada llamada a `beginMacro()` debe tener una llamada correspondiente a ` endMacro()`.

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

La pila se habilita y se emiten las señales correspondientes 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 algún comando 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 se ha repetido.

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

Nota: Funciónde lectura para la propiedad canRedo.

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.

Nota: Señalde notificación para la propiedad canRedo.

bool QUndoStack::canUndo() const

Devuelve « true » si hay algún comando disponible para deshacer; en caso contrario, devuelve « false ».

Esta función devuelve ` false ` si la pila está vacía o si el comando situado en la parte inferior de la pila ya se ha deshecho.

Sinónimo de index() == 0.

Nota: Funciónde lectura para la propiedad canUndo.

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.

Nota: Señalde notificación para la propiedad canUndo.

[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 se encuentra en estado «limpio»; en caso contrario, esta señal indica que ha salido de dicho estado.

Nota: Señalde notificación para la propiedad clean.

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

int QUndoStack::cleanIndex() const

Devuelve el índice limpio. Se trata del índice en el que se llamó a setClean().

Es posible que una pila no tenga un índice limpio. Esto ocurre si se guarda un documento, se deshacen algunos comandos y, a continuación, se añade un nuevo comando a la pila. Dado que push() elimina todos los comandos deshechos antes de añadir el nuevo comando, la pila no puede volver al estado limpio. En este caso, esta función devuelve -1. También se puede devolver -1 tras una llamada explícita a resetClean().

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

void QUndoStack::clear()

Borra la pila de comandos eliminando todos los comandos que contiene y devuelve la pila a su estado inicial.

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

Esta función se suele utilizar cuando se descarta el contenido del documento.

Véase también QUndoStack().

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

Devuelve un puntero const al comando en index.

Esta función devuelve un puntero const, ya que modificar un comando, una vez que se ha insertado en la pila y se ha ejecutado, casi siempre provoca la corrupción del estado del documento si posteriormente se deshace o se rehace el comando.

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

int QUndoStack::count() const

Devuelve el número de comandos que hay en la pila. Los comandos de macro se cuentan como un solo comando.

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

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

Crea un objeto «redo» de tipo ` QAction ` con el ` parent` indicado.

Al activar esta acción, se invocará a redo(). El texto de esta acción es el texto del comando que se volverá a ejecutar en la siguiente llamada a redo(), precedido por el prefijo especificado en prefix. Si no hay ningún comando disponible para deshacer, esta acción quedará desactivada.

Si prefix está vacío, se utiliza la plantilla predeterminada «Redo %1» en lugar del prefijo. Antes de Qt 4.8, se utilizaba el prefijo «Redo» de forma predeterminada.

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

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

Crea un objeto « QAction » de deshacer con el « parent » indicado.

Al activar esta acción, se llamará a undo(). El texto de esta acción es el texto del comando que se deshará en la siguiente llamada a undo(), precedido por el prefijo especificado en prefix. Si no hay ningún comando disponible para deshacer, esta acción estará desactivada.

Si prefix está vacío, se utiliza la plantilla predeterminada «Deshacer %1» en lugar del prefijo. Antes de Qt 4.8, se utilizaba el prefijo «Deshacer» de forma predeterminada.

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

void QUndoStack::endMacro()

Finaliza la composición de un comando de macro.

Si se trata de la macro más externa de un conjunto de macros anidadas, esta función ejecuta indexChanged() una vez para todo el comando de macro.

Véase también beginMacro().

int QUndoStack::index() const

Devuelve el índice del comando actual. Se trata del comando que se ejecutará en la próxima llamada a redo(). No siempre es el comando situado en la parte superior de la pila, ya que es posible que se hayan deshecho varios comandos.

Véanse 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 se vuelve a ejecutar un comando. Cuando se deshace o se vuelve a ejecutar un comando de macro, o cuando se llama a ` setIndex()`, esta señal se emite solo una vez.

idx Especifica el índice del comando actual, es decir, el comando que se ejecutará en la próxima llamada a redo().

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

bool QUndoStack::isClean() const

Si la pila se encuentra en estado «clean», devuelve « true »; en caso contrario, devuelve « false ».

Nota: Funcióngetter para la propiedad clean.

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

void QUndoStack::push(QUndoCommand *cmd)

Añade cmd a la pila o lo fusiona con el comando ejecutado más recientemente. En cualquiera de los dos casos, ejecuta cmd llamando a su función redo().

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

Tras llamar a ` QUndoCommand::redo()` y, si procede, 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 se eliminarán de la pila.

En todos los demás casos, simplemente se añade cmd a la pila.

Si se han deshecho comandos antes de que se insertara cmd, se eliminan el comando actual y todos los comandos que lo preceden. Por lo tanto, cmd siempre acaba siendo el comando más alto de la pila.

Una vez que se añade un comando a la pila, esta se hace cargo de él. No hay métodos para recuperar el comando, ya que modificarlo después de su ejecución casi siempre provocaría la corrupción del estado del documento.

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

[slot] void QUndoStack::redo()

Repite 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 se ha revertido, esta función no realiza ninguna acción.

Si QUndoCommand::isObsolete() devuelve «true» para el comando actual, dicho comando se eliminará de la pila. Además, si el índice de limpieza es mayor o igual que el índice del comando actual, el índice de limpieza se restablece.

Véanse también « undo()» y « index()».

QString QUndoStack::redoText() const

Devuelve el texto del comando que se volverá a ejecutar en la próxima llamada a ` redo()`.

Nota: Funcióngetter para la propiedad redoText.

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.

Nota: Señalde notificación para la propiedad redoText.

[slot] void QUndoStack::resetClean()

Sale del estado «limpio» y emite un cleanChanged() si la pila estaba limpia. Este método restablece el índice de limpieza a -1.

Normalmente se invoca en los siguientes casos, cuando un documento:

  • creado a partir de una plantilla y no se ha guardado, por lo que aún no se le ha asignado ningún nombre de archivo.
  • se ha restaurado a partir de 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 un cleanChanged() si la pila aún no estaba limpia.

Normalmente se invoca esta función, por ejemplo, al guardar un documento.

Cada vez que la pila vuelve a este estado mediante el uso de los comandos de deshacer/rehacer, emite la señal cleanChanged(). Esta señal también se emite cuando la pila sale del estado «limpia».

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

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

Llama repetidamente a undo() o redo() hasta que el índice de comando actual alcance idx. Esta función se puede utilizar para avanzar o retroceder en el estado del documento. indexChanged() solo 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 situado justo debajo del comando actual llamando a ` QUndoCommand::undo()`. Disminuye el índice del comando actual.

Si la pila está vacía, o si el comando situado en la parte inferior de la pila ya se ha deshecho, esta función no realiza ninguna acción.

Una vez deshecho el comando, si ` QUndoCommand::isObsolete()` devuelve ` true`, el comando se eliminará de la pila. Además, si el índice de limpieza es mayor o igual que el índice del comando actual, el índice de limpieza se restablece.

Véanse también ` redo()` y ` index()`.

QString QUndoStack::undoText() const

Devuelve el texto del comando que se deshará en la próxima llamada a ` undo()`.

Nota: Funcióngetter para la propiedad undoText.

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 de texto de la acción de deshacer devuelta por ` createUndoAction()`. ` undoText ` especifica el nuevo texto.

Nota: Señalde notificación para la propiedad undoText.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.