UndoManager class

An UndoManager observes and records model and diagram changes in transactions and supports undo/redo operations. You will need to set the #isEnabled property to true in order for the UndoManager to record changes and for users to perform an undo or a redo.

Typically an operation will call #startTransaction, make some changes to the Model and/or Diagram, and then call #commitTransaction. Any ChangedEvents that occur will be recorded in a Transaction object. If for some reason you do not wish to complete the transaction successfully, you can call #rollbackTransaction instead of #commitTransaction.

For convenience the Diagram#commit and Model#commit methods execute a function within a transaction and then perform a commit, or else a rollback upon an error.

The #history property is a list of Transactions. #commitTransaction will add the #currentTransaction to the #history list. #rollbackTransaction will undo the changes remembered in the #currentTransaction and then discard it, without changing the #history. You can limit how many transactions are remembered in the history by setting #maxHistoryLength.

Transactions may be nested. Be sure to call either #commitTransaction or #rollbackTransaction for each call to #startTransaction. Avoid repeated start-commit-start-commit calls as a result of a user's actions. Instead, start, make all changes, and then commit.

If you want to restore the diagram to the state before the latest complete transaction, call #undo. Call #redo to change the diagram to a later state. If after some number of undo's you start a transaction, all of the history after the current state is discarded, and a new transaction may be recorded. You cannot undo or redo during a transaction.

Initially each Model has its own UndoManager. UndoManagers may be shared by multiple Models by replacing the standard Model#undoManager created by the model constructor.

There are several informational properties:

• #isInTransaction is true when a top-level transaction has been started that has not yet been committed or rolled-back.
• #currentTransaction holds the flattened list of all ChangedEvents that have happened within the current transaction.
• #transactionLevel indicates the current depth of nesting.
• #nestedTransactionNames holds the stack of transaction names supplied to #startTransaction calls.
• #history holds only complete top-level transactions.
• #isUndoingRedoing is true during a call to #undo or #redo.
• #historyIndex indicates which Transaction in the #history is the next to be "undone"; this is decremented by each undo and incremented by each redo.
• #transactionToUndo and #transactionToRedo indicate which Transaction may be undone or redone next, if any.
• #models returns an iterator over all of the Models that this UndoManager is handling.

A transaction may not be ongoing when replacing a Diagram#model, because it would not make sense to be replacing the UndoManager (the Model#undoManager) while changes are being recorded.

Replacing a Diagram#model copies certain properties from the old UndoManager to the new one, including #isEnabled and #maxHistoryLength.

Available extensions

• UndoManager$Typings

Annotations

• @JS()
• @staticInterop

Constructors

UndoManager()

factory

Properties

currentTransaction ↔ Transaction?

Available on UndoManager, provided by the UndoManager$Typings extension

This read-only property returns the current Transaction for recording additional model change events. This is initialized and augmented by #handleChanged before it is added to #history by a top-level call to #commitTransaction. The value will be null between transactions.

getter/setter pair

hashCode → int

The hash code for this object.

no setter, inherited

history ↔ List<Transaction>

Available on UndoManager, provided by the UndoManager$Typings extension

This read-only property returns the whole history, a list of all of the Transactions, each representing a transaction with some number of ChangedEvents.

getter/setter pair

historyIndex ↔ num

Available on UndoManager, provided by the UndoManager$Typings extension

This read-only property returns the index into #history for the current undoable Transaction. The value is -1 if there is no undoable Transaction to be undone.

getter/setter pair

isEnabled ↔ bool

Available on UndoManager, provided by the UndoManager$Typings extension

Gets or sets whether this UndoManager records any changes. The default value is false -- you need to set this to true if you want the user to be able to undo or redo.

getter/setter pair

isInTransaction ↔ bool

Available on UndoManager, provided by the UndoManager$Typings extension

This read-only property is true after the first call to #startTransaction and before a corresponding call to #commitTransaction or #rollbackTransaction.

getter/setter pair

isUndoingRedoing ↔ bool

Available on UndoManager, provided by the UndoManager$Typings extension

This read-only property is true during a call to #undo or #redo.

getter/setter pair

maxHistoryLength ↔ num

Available on UndoManager, provided by the UndoManager$Typings extension

Gets or sets the maximum number of transactions that this undo manager will remember. When a transaction is committed and the number exceeds this value, the UndoManager will discard the oldest transaction(s) in order to meet this limit. The initial value is 999. Any new value must be an integer. A negative value is treated as if there were no limit. A zero value will not remember any Transactions in the #history, but will allow commits and rollbacks to occur normally, including raising "Transaction" type ChangedEvents.

getter/setter pair

models ↔ Iterator<Model>

Available on UndoManager, provided by the UndoManager$Typings extension

This read-only property returns an iterator for all of the Models that this UndoManager is handling.

getter/setter pair

nestedTransactionNames ↔ List<String>

Available on UndoManager, provided by the UndoManager$Typings extension

This read-only property returns a stack of ongoing transaction names. The outermost transaction name will be the first item in the list. The last one will be the name of the most recent (nested) call to #startTransaction.

getter/setter pair

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

transactionLevel ↔ num

Available on UndoManager, provided by the UndoManager$Typings extension

This read-only property returns the current transaction level. The value is zero when there is no ongoing transaction. The initial value is zero. #startTransaction will increment this value; #commitTransaction or #rollbackTransaction will decrement it. When this value is greater than zero, #canUndo and #canRedo will be false, because additional logically related model change events may occur.

getter/setter pair

transactionToRedo ↔ Transaction?

Available on UndoManager, provided by the UndoManager$Typings extension

This read-only property returns the Transaction in the #history to be redone next. The value may be null if the UndoManager is not ready to perform a redo.

getter/setter pair

transactionToUndo ↔ Transaction?

Available on UndoManager, provided by the UndoManager$Typings extension

This read-only property returns the Transaction in the #history to be undone next. The value may be null if the UndoManager is not ready to perform an undo.

getter/setter pair

Methods

addModel(Model model) → void

Available on UndoManager, provided by the UndoManager$Typings extension

Make sure this UndoManager knows about a Model for which it may receive ChangedEvents when the given Model is changed. The model will also receive notifications about transactions and undo or redo operations.

canRedo() → bool

Available on UndoManager, provided by the UndoManager$Typings extension

This predicate returns true if you can call #redo. This will return false if #isEnabled is false (as it is by default), if any transaction is ongoing, or if there is no #transactionToRedo that can be redone. @return {boolean} true if ready for #redo to be called.

canUndo() → bool

Available on UndoManager, provided by the UndoManager$Typings extension

This predicate returns true if you can call #undo. This will return false if #isEnabled is false (as it is by default), if any transaction is ongoing, or if there is no #transactionToUndo that can be undone. @return {boolean} true if ready for #undo to be called.

clear() → void

Available on UndoManager, provided by the UndoManager$Typings extension

Clear all of the Transactions and clear all other state, including any ongoing transaction without rolling back. However, this maintains its references to its Models.

commitTransaction([String? tname]) → bool

Available on UndoManager, provided by the UndoManager$Typings extension

Commit the current transaction started by a call to #startTransaction.

copyProperties(UndoManager old) → void

Available on UndoManager, provided by the UndoManager$Typings extension

(undocumented) Copy persistent properties from an old UndoManager to this new one. This is called by the Diagram#model property setter. @expose @param old

discardHistoryAfterIndex() → void

Available on UndoManager, provided by the UndoManager$Typings extension

After an undo, call this to discard all of the transactions after this point in the history, as indicated by the #historyIndex. This method is called when a transaction occurs after some number of undo's without the same number of redo's, in order to remove all of the transactions that happened after the current history point, and then adding the new transaction.

handleChanged(ChangedEvent e) → void

Available on UndoManager, provided by the UndoManager$Typings extension

Maybe record a ChangedEvent in the #currentTransaction. This calls #skipsEvent to see if this should ignore the change. If #skipsEvent returns false, this creates a copy of the ChangedEvent and adds it to the #currentTransaction. If there is no #currentTransaction, this first creates and remembers it.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

redo() → void

Available on UndoManager, provided by the UndoManager$Typings extension

After an #undo, re-perform the changes in #transactionToRedo. #canRedo must be true for this method to have any effect.

removeModel(Model model) → void

Available on UndoManager, provided by the UndoManager$Typings extension

Inform this UndoManager that it will no longer be receiving ChangedEvents when the given Model is changed. The model will no longer receive notifications about transactions and undo or redo operations.

rollbackTransaction() → bool

Available on UndoManager, provided by the UndoManager$Typings extension

Rollback the current transaction started by a call to #startTransaction, undoing any changes.

skipsEvent(ChangedEvent e) → bool

Available on UndoManager, provided by the UndoManager$Typings extension

This predicate is called by #handleChanged to decide if a ChangedEvent is not interesting enough to be remembered.

startTransaction([String? tname]) → bool

Available on UndoManager, provided by the UndoManager$Typings extension

Begin a transaction, where the changes are held by a Transaction object as the value of #currentTransaction. You must call either #commitTransaction or #rollbackTransaction afterwards.

toString() → String

A string representation of this object.

inherited

undo() → void

Available on UndoManager, provided by the UndoManager$Typings extension

Reverse the effects of the #transactionToUndo. #canUndo must be true for this method to have any effect.

Operators

operator ==(Object other) → bool

The equality operator.

inherited