Preventing Multiple Undo/Redo Units When Triggering an Add-on from the EventXFMod Cell in Visio 2002

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

 

Microsoft Corporation

September 2001

Applies to:
   Microsoft Visio Standard 2002
   Microsoft Visio Professional 2002

Summary: This article describes how to trigger an add-on using the EventXFMod cell and prevent it from storing multiple undo/redo units in the Undo manager. (8 printed pages)

Contents

Introduction
Overview
Triggering an Add-on from the EventXFMod Cell and Tracking Its State
Passing the Appropriate Arguments to the Add-on Using the Run Method
Preventing Multiple Undo/Redo Units within a Single Undo Scope
Additional Information

Introduction

In Microsoft® Visio® 2002, when you want to trigger an add-on in response to a change in a particular shape's position, size, or orientation on the page, you'll probably use the shape's EventXFMod cell in the ShapeSheet® spreadsheet. If you use this cell to trigger an add-on and your add-on changes this particular shape's position, size, or orientation on the page while it's running, your add-on will trigger itself again.

For example, you enter a formula for X shape's EventXFMod cell that triggers the add-on, ChangePosition. In response to a change in X shape's position, size, or orientation on the page, Visio evaluates X shape's EventXFMod cell and triggers the ChangePosition add-on. While the add-on is running, it changes X shape's position, which causes a shape event for X shape, and in turn evaluates X shape's EventXFMod cell and triggers the ChangePosition add-on again while it's already running.

Each time the add-on is triggered while it's already running, Visio stores an undo/redo unit in the Undo manager, instead of storing just one unit for the entire add-on session. The end result is that a user will see multiple undo/redo actions in the Undo and Redo lists instead of what they expect to see: just one undo/redo action for the add-on.

Overview

This article describes how to prevent an add-on triggered from the EventXFMod cell from storing multiple undo/redo units in the Undo manager every time the add-on is triggered while it's already running. First, it describes how to trigger an add-on from a shape's EventXFMod cell and track the state of the add-on. Second, it describes the particular arguments to pass to the add-on's Run method for this technique. Last, it describes how to create an undo scope for the add-on and perform actions within the scope that prevent multiple undo/redo units in the Undo manager.

Figure 1. Overview of the technique described in this article

**Note   **In Visio 2000, when a user chooses an Undo or Redo command that causes evaluation of a shape's EventXFMod cell, the Application object's IsUndoingOrRedoing property sometimes incorrectly returns a value of False. Therefore, the technique described in this article doesn't work for Visio 2000 because the value of the IsUndoingOrRedoing property isn't reliable.

Triggering an Add-on from the EventXFMod Cell and Tracking Its State

Using Visio, you can trigger and respond to events in numerous ways. Use the EventXFMod cell in the Events section of a shape's ShapeSheet spreadsheet to trigger an event when the shape's position, size, or orientation on the page is changed — when the shape is transformed (XF), hence the name of the cell. When one of these actions happens, Visio evaluates the EventXFMod cell's formula, in which you can use the RUNADDON or RUNADDONWARGS functions to trigger an add-on. After you've triggered the add-on, you can use a user-defined cell for the shape to store a value that represents the state of the add-on: whether it's running or not in response to an action performed on the shape.

Figure 2. User action and cell evaluation process

In the examples below, you first create a new user-defined cell named AddonRunning for a particular shape. Then, you enter a formula in the shape's EventXFMod cell that performs the following actions:

• Determine the value of the User.AddonRunning cell using the GETREF function to find out whether the add-on is running.

  **Note   **In the EventXFMod cell, use the GETREF function to get the value of another cell so Visio doesn't recalculate the formula in the EventXFMod cell each time the value of the referenced cell changes.

• If the add-on isn't already running, run the add-on named Addon and pass it arguments using the RUNADDONWARGS function.

• If the add-on is running, don't do anything.

To create a user-defined cell to track the state of an add-on for a particular shape

1. Select a shape, and then on the Window menu, click Show ShapeSheet.

   **Note   **Select the shape you want to use throughout this entire article.

2. In the ShapeSheet window, go to the User-defined Cells section.

3. In the User-defined Cells section, right-click a row, and then click Insert Row.

4. Double-click the name of the new row, and then replace the default row name with AddonRunning, and then press ENTER.

   Visio names the row User.AddonRunning.

5. For the User.AddonRunning value, type "0", and then press ENTER.

To enter a formula in the shape's EventXFMod cell that triggers an add-on

1. In the same shape's ShapeSheet spreadsheet, go to the Events section.

2. In the Events section, for the EventXFMod cell, enter this value:

   =IF(GETREF (User.AddonRunning)=0, RUNADDONWARGS("Addon", "cmd=EventXFMod"), 0)

Passing the Appropriate Arguments to the Add-on Using the Run Method

A change in the shape's position, size, or orientation on the page triggers the add-on. Then you use the Run method to run the add-on and pass arguments to it. Pass arguments to the add-on's Run method so it behaves in the following ways:

• If the add-on is triggered by the Undo or Redo command, don't do anything; just let the Visio engine handle it.

  You can use the IsUndoingOrRedoing property of the Application object to determine whether the add-on was triggered by the Undo or Redo command. Always test the state of Visio using this property if you are performing actions within your Run method that can't be undone.

• If the add-on wasn't triggered by the Undo or Redo command and it's not already running, start an undo scope.

  You can use the ResultIU property to get the value of the User.AddonRunning cell for a particular shape and find out if the add-on was already triggered as a result of an action performed on the shape. If the value is 0, the add-on isn't already running. If it's 1, the add-on is already running in response to an action performed on the shape.

  

  Figure 3. Add-on evaluation process

Preventing Multiple Undo/Redo Units within a Single Undo Scope

One of the first things your add-on must do is start an undo scope by using the BeginUndoScope method of the Application object. Once you've started the undo scope, mark the shape that triggered the add-on so you know your add-on is running and which shape triggered it. Then, run your add-on. Just before your add-on finishes, flush the Visio buffers to trigger pending EventXFMod cell events caused by your add-on, unmark the shape so you know your add-on isn't running anymore, and then end the undo scope by using the EndUndoScope method of the Application object. This overall process prevents an add-on that was triggered from an EventXFMod cell from storing multiple undo/redo units in the Undo manager.

Figure 4. Undo scope and actions that prevent multiple undo/redo units

In the example below, you create an undo scope and perform the actions that prevent multiple undo/redo units in the Undo manager for the add-on named Addon. And, you mark the same shape you've been working with throughout this article.

To create an undo scope for your add-on and prevent multiple undo/redo units in the Undo manager

1. Start the undo scope. For example, use the following code:

   nID=Application.BeginUndoScope("Addon")
   

2. Mark the shape that triggered the add-on using the ResultIU property to set the value of the shape's User.AddonRunning cell to 1.

3. Let your add-on run and perform its actions that cause evaluation of the EventXFMod cell while the add-on is running, such as moving the shape that triggered the add-on.

4. While the value of the User.AddonRunning cell is still 1, force the Visio engine to flush its buffers by updating the screen twice. For example, use the following code:

   bRedraw = Application.ScreenUpdating
   Application.ScreenUpdating = !bRedraw
   Application.ScreenUpdating = bRedraw
   

   **Note   **Updating the screen has nothing to do with preventing multiple undo/redo units. Updating the screen twice is just a trick you can use to flush the Visio buffers.

5. Unmark the shape that triggered the add-on using the ResultIU property to set the value of the shape's User.AddonRunning cell to 0.

6. End the scope. For example, use the following code:

   Application.EndUndoScope(nID, True)
   

Additional Information

• For more information on subjects related to this article, use the words in Table 1 to search Microsoft Visio 2002 online Help (on the Help menu, click Developer Reference).

  Table 1. Search Words for Visio Help

  For information about	Use these words to search Visio Help
  User-defined Cells section	user-defined
  Events section	events
  EventXFMod cell	eventxfmod cell
  GetRef function	getref function
  RUNADDONWARGS function	runaddonwargs
  Formulas	formula
  Functions	function
  Undo scope	undo scope
  Run method	run method
  ResultIU property	resultiu

• For more information about events, running add-ons and the Undo manager, see Developing Visio Solutions for Microsoft Visio 2002

• To examine a Visio solution with shapes that demonstrate this technique, open the Timeline solution in Microsoft Visio 2002. On the File menu, point to New, point to Project Schedule, and then click Timeline. Examine any of the milestone, interval, or marker shapes on the Timeline Shapes stencil.