What is the Undo Manager?
This lesson provides a basic overview of the Undo Manager API.
The Undo Manager is an API that provides the handlers and messages necessary to implement undo/redo in your application. The API itself provides no actual undo functionality but rather provides a system that you can extend to support the undo requirements of your application.
Important Note: The Undo Manager requires Revolution 3.0 or later. It relies on multi-dimensional arrays which were introduced in this version.
The Undo Stack
To use the undo manager your application can add undo actions to an undo stack. Once there are undo actions in an undo stack you can undo that action. Whenever you undo an action the action is moved to the redo stack at which point you can redo the action.
You control how an undo action is handled by defining undo types. With each undo type that you define you register callback handlers that will be called when:
- You add an undo action to the queue.
- When you undo/redo the undo action.
- The undo action is removed from the queue (in case you need to clean anything up).
When adding an undo action to the undo stack you assign it one of the undo action types that you have registered. This will associate the undo action with the registered callbacks.
Here is an example of how you would register an "add person" undo action type that could be used when adding a person to an address book application.
undoRegisterType "add person", "uiUndoStoreMementoForAddOrRemove", "uiUndoAddOrRemove", \ empty, the long id of me, "delete person"
Each undo action includes a memento that contains all of the information necessary to undo or redo an action. A memento is an array with one or more keys. It is your job to populate the memento when you add the undo action to the undo queue.
For example, if someone adds a person to an address book application then the memento for the undo action might be the internal id of the new person.
-- Create new person record... -- The id of the new record is stored in theId put theID into theMementoA["id"] undoStoreUndo "add person", "Create Person", theMementoA
The memento array that you store with an undo action is included as a parameter when the undo manager sends callback messages associated with an undo action type.