Creating Undo Scopes in Your Add-on

3 4

In some cases, the Microsoft Visio engine cannot automatically manage the undoable actions in an add-on. If an add-on is a stand-alone program, for example, Visio cannot detect when the add-on begins and ends. Or if a program is running modeless, Visio cannot be aware of all the operations that the add-on performs. For this reason, Visio provides mechanisms for you to create your own undo scopes.

In addition to consolidating operations into single undoable actions, you can also use undo scopes to determine if events that your program receives result from actions in the program itself. You can do this by creating undo scopes, and then checking each scope's ID inside your event handlers.

Creating an Undo Scope

To create an undo scope, use the BeginUndoScope and EndUndoScope methods of the Application object. You can create multiple scopes inside an add-on, and you can nest undo scopes inside each other.

The BeginUndoScope method opens a new scope and returns an ID for the scope. While the scope is open the Visio Undo manager gives it any new undo units that are added to the stack. The Visio engine also queues the EnterScope event so that later it can pass the scope ID and description to your program.

Consider the following guidelines when creating undo scopes:

• BeginUndoScope and EndUndoScope calls must be balanced.
• Undo scopes should be opened and closed within a function or subroutine. If you leave an undo scope open, user actions can get logged into the middle of the scope.

The EndUndoScope method takes an argument of True or False, which indicates whether you want to accept or cancel the changes made during the scope. You can use this as a technique for rolling back changes if you or your user decides to cancel your add-on. For details about the BeginUndoScope and EndUndoScope methods, see the Microsoft Developer Reference (on the Help menu, click Developer Reference).

Associating Events with an Undo Scope

You can use an undo scope to determine whether events you receive are the result of an action taken by your add-on.

When you open an undo scope with the BeginUndoScope method, it returns a scope ID and fires the EnterScope event. When you close an undo scope with the EndUndoScope method, an ExitScope event fires. Any events caused when your undo scope is open fire between the EnterScope and ExitScope events.

When you receive events, you can use the scope ID to determine if an event is a result of an action taken in the undo scope.

To determine if your undo scope caused an event

1. Save the scope ID that is returned from the BeginUndoScope method in a program variable.
2. When you receive an event in your event handler, get the IsInScope property of the Application object, passing it the saved scope ID.
3. If the IsInScope property returns True, the event is a result of an action taken in your undo scope.
4. Create an event handler for the ExitScope event and clear your scope ID variable when the scope closes.