Event Formulas | Developing Microsoft Visio Solutions (Pro-Documentation)

3 4

The Microsoft Visio engine has numerous ways of triggering and responding to events. You can put formulas into ShapeSheet cells that perform an action, such as running a macro or navigating to another drawing page, in response to an event. These formulas can be used in the Events section, which handles a select group of events, or in other cells. You can also use the DEPENDSON function to simulate other events. In addition to the DEPENDSON function, there are several built-in functions that are particularly useful in event handling because they perform actions.

Visio also supports the use of Automation for writing code to handle events. With Automation, you can develop powerful solutions that use Microsoft Visual Basic for Applications (VBA) programs, stand-alone programs, and other more advanced approaches to handling events. For details, see Chapter 21, Handling Visio Events.

Using Cells in the Events Section

You can define how a shape responds to specific user actions by writing Visio formulas that handle events. Whenever the user performs one of the four actions described in the following table, the formula in the corresponding ShapeSheet cell is evaluated. The Events section of a ShapeSheet window contains the following cells; when a user performs any of these actions, the formula in the cell is evaluated.

Events section cells

Cell	Event that triggers the formula
TheText	The shape's text or formatting is changed, or the text requires recomposition.
EventXFMod	The shape's position, size, or orientation on the page is changed.
EventDblClick	The shape is double-clicked.
EventDrop	A new instance is created by pasting, duplicating, or CTRL+dragging a shape, or by dragging and dropping a master.
TheData	Reserved for future use.

By entering formulas in the Events section cells, you define how the shape responds to each event. Unlike most ShapeSheet formulas, event formulas are evaluated only when the event happens, not when you enter the formula or when cells referenced by the formula change. This means that Events cells behave somewhat differently than other ShapeSheet cells, as follows:

The value displayed in an Events cell may appear to be out-of-date or inconsistent with the cell's formula. For example, suppose you entered this formula in the EventDblClick cell:
```
 = Width > 1 in. 
```
This formula returns true or false . However, the formula is evaluated when the user double-clicks the shape, not when the shape is resized, so the value displayed in the cell reflects what was true for the shape the last time it was double-clicked.
The order of evaluation and the number of times an event is evaluated are unpredictable. For example, if a shape is resized, both TheText and EventXFMod are evaluated, but the order in which these events trigger evaluation is undefined. However, Visio evaluates each cell at least once in the order it chooses.

Simulating Events with the DEPENDSON Function

You can use the DEPENDSON function to simulate events in other ShapeSheet sections such as the Scratch section. Using this function enables you to respond to events other than those provided in the Events section, and it also provides finer control over your event handling.

For example, if you put the following formula in a Scratch cell for a shape, the Visio engine opens the shape's text block whenever the shape is moved:

 OPENTEXTWIN() + DEPENDSON(PinX, PinY)

In another example, if you put the following formula in a Scratch cell, the add-on Myprog.exe is launched whenever the shape is flipped in either direction:

 RUNADDON("my_prog.exe") + DEPENDSON(FlipX, FlipY)

Note

The DEPENDSON function has no effect when used in an Events or Action cell. For details, see the DEPENDSON function in the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

Functions that Perform Actions

Microsoft Visio includes built-in functions that perform actions rather than produce a value, making them especially useful in event formulas. The following table shows a partial list of functions; for a complete list as well as details about function syntax, see the Microsoft Visio Developer Reference(on the Help menu, click Developer Reference).

Functions to use in event formulas

Function name	Description
CALLTHIS("procedure", ["project"], [arg1,arg2,.)	Calls a procedure in a VBA project and passes the procedure a reference to the Shape object that contains the CALLTHIS formula being evaluated, along with any arguments specified in that formula. For example: CALLTHIS("ThisDocument.myProc",, Height, Width)
GOTOPAGE("pagename")	Displays the indicated page in the currently active window. A URL can also be used here. GOTOPAGE("Page-2")
OPENFILE("filename")	Opens a file in a new window. If multiple files are listed, the requests are queued and executed in order of evaluation, with the last named document receiving final focus. If the current Visio document is activated for visual (in-place) editing, a new Visio instance is launched with the requested file name.
OPENSHEETWIN()	Opens and displays a ShapeSheet window showing the shape that contains this formula.
OPENTEXTWIN()	Opens the text block for the shape that contains this formula.
PLAYSOUND("filename"\| "alias", isAlias, beep, synch)	On systems with a sound card, plays the sound recorded in filename, or plays the system alias for a sound if isAlias is a non-zero number. If the sound cannot be played, Visio can beep to indicate an error. Sounds can be played asynchronously or synchronously. For example: PLAYSOUND ("chord.wav", 0, 0, 0) Plays the wave audio file chord.wav synchronously with no warning beep.
RUNDADDON("string")	Launches the specified macro or add-on, or executes VBA code. Any statement that can be entered in the VBA Immediate window can be specified as a RUNADDON argument.
RUNADDONWARGS ("filename","arguments")	Launches an add-on and passes it the given argument string.
SETF(GetRef(cell), formula)	When evaluated, the result of the expression in formula becomes the new formula of the specified cell. If formula is enclosed in quotation marks, the quoted expression is written to the cell. For example: SETF (GetRef(Scratch.A1), Evaluates the formula =Scratch.A1+1 and sets the Scratch.A1+1) formula of the Scratch.A1 cell to the result, which is its previous value incremented by 1.

Performance Considerations for Event Formulas

Because event formulas are evaluated each time the event occurs, they can affect the usability and performance of your shapes. Follow these general guidelines:

Use event formulas sparingly Avoid event formulas for frequent events such as moving or sizing the shape (EventXFMod) or editing its text (TheText). Handling these events can interrupt the user's workflow and make shapes awkward to use.
Keep event formulas simple A complex formula takes longer to evaluate, which slows the performance of the shape.
Be aware that some actions take longer than others Even a simple event formula may trigger a time-consuming action. For example, it takes longer to launch a stand-alone executable add-on than to run a macro, and longer to navigate to a Web page than to navigate to another page in the same Visio document.