The Visio Undo Manager

3 4

The Microsoft Visio engine creates an undo unit for every Visio command that changes the state of a document. An undo unit describes what has changed—it encapsulates all the information that's necessary to undo a change that a user doesn't want.

Every undoable action has a corresponding undo unit. For each undoable action that a user performs in the user interface, the Visio instance creates an undo unit that appears in the Undo list on the Standard toolbar.

Figure 25-1 Example of list of undoable actions in the user interface.

Actions caused by running an add-on are handled differently from actions in the user interface. Users who run an add-on from the Macros submenu (on the Tools menu, click Macros) might think of that action as being similar to dropping a shape on a page—as a single undoable action. The user most likely expects to undo any add-on changes in a single action. For this reason, whenever an add-on is invoked from Visio, the add-on's undoable actions are consolidated inside an undo scope and are presented to the user as a single undoable action.

For details on creating your own undo scopes, see Creating Undo Scopes in Your Add-on later in this chapter.

An Undo/Redo Overview

Every Visio instance maintains one Undo manager to manage the undo and redo stacks. When a user clicks Undo, the Visio Undo manager takes the most recently added undo unit from the undo stack, and the undo unit carries out its actions and creates a corresponding object on the redo stack.For example, if a user performs three actions on the drawing page, the Visio Undo manager would look something like the following illustration:

Figure 25-2 The state of the undo/redo stacks after three undoable actions.

If the user then clicks the Undo command, or your program invokes the Undo method of the Application object, the Visio Undo manager would appear as the following illustration shows:

Figure 25-3 The state of the undo/redo stacks after one action is undone.

How the Visio Undo Manager Works with an Add-on

An add-on often performs multiple undoable actions—for example, it might change the fill of every shape on a page to blue. If a user didn't like this change and wanted to undo it, he or she would expect the Undo command to restore the drawing to its state before the add-on ran.

For this reason, the Visio engine consolidates the sequence of actions caused by an add-on into a single undoable action. Every time an add-on is invoked from a Visio instance, an undo scope begins. The undo scope ends when the add-on finishes. Everything inside of this scope is treated as a single undoable action.

For example, if an add-on executes three Visio commands, the undo stack would look like the following illustration after the add-on runs:

Figure 25-4 The state of the undo/redo stacks after an add-on is run that performs three undoable actions.

If the user then chose to undo the changes made by the add-on, the user would see a single command in the Undo list on the Standard toolbar and on the Edit menu, all three actions would be undone, and the undo queue would look like the previous illustration.

Figure 25-5 The state of the undo/redo stacks after choosing Undo for an add-on that performs three undoable actions.

Tip

---

When you include an undoable action inside an event handler, check the Application object's IsUndoingOrRedoing property first. You want to perform undoable actions only when this flag is False. If IsUndoingOrRedoing returns True, the event handler is being called as a result of an undo or redo action; if any undoable actions are performed, the redo stack is destroyed.