Controlling when Your Program Runs | Developing Microsoft Visio Solutions (Pro-Documentation)

3 4

You can run a program in a number of ways depending on what type of program you write and where you install external program files. Here are some of your options:

Running a program when a Visio instance is started

To run your program every time Microsoft Visio is started, install your program's executable (EXE) or Visio library (VSL) file in the Visio startup folder specified on the File Paths tab (on the Tools menu, click Options).

To load a Component Object Model (COM) add-in when Visio is started, you must register it with a load behavior of Startup. When the add-in is loaded, it remains loaded until it is explicitly unloaded.

Note

When a COM add-in loads, it might not necessarily run until an event occurs that it is listening for. For more details on implementing COM add-ins, see Chapter 23, Using COM Add-ins in a Visio Solution.

Running a program from the Macros submenu or dialog box

To run your program—EXE or VSLfile , or Microsoft Visual Basic for Applications (VBA) macro—from the Macros dialog box, install an external program's EXE or VSL file in the Add-ons path specified on the File Paths tab. All programs in this path appear in the Macros dialog box and on the Macros submenu along with any public VBA macros stored with the Visio document that is open.

Figure 26-2. Macros dialog box.

Figure 26-2 Macros dialog box.

Loading a COM add-in program from the COM Add-Ins dialog box

If you haven't set your COM add-in to load when Visio is started or to load on demand, you or your solution's users can load the COM add-in from the COM Add-Ins dialog box. Because the add-in must be registered, you don't need to specify a path for it. All registered COM add-ins appear in the COM Add-Ins dialog box (on the Tools menu, point to Macros, and then click COM Add-Ins).

Note

Binding a program to a cell in the Actions or Events section

You can run a program when a user right-clicks a shape and chooses a menu item, or when a shape event occurs, such as a double-click event. To run any program from a shape's shortcut menu, enter a formula that uses the Visio runaddon function in the Action cell of a row in the shape's Actions section, and enter the text of the menu item in the Menu cell. The RUNADDON function can run any add-on or macro in your VBA project.

figure 26-3. an action row in a shape's actions section.

Figure 26-3 An Action row in a shape's Actions section.

Unless you specify a full path, Visio looks for your program in the Add-ons path specified on the File Paths tab.

You can also set an action for a particular shape in the Action dialog box (available when the ShapeSheet window is active) by clicking in an Action cell and clicking Action on the Edit menu.

Figure 26-4. Action dialog box.

Figure 26-4 Action dialog box.

To pass command-line arguments to your program, use the Visio runaddonwargs function—it is not used with VBA programs, only add-ons. For example, to run an external program named MyProg.exe:

 = RUNADDONWARGS("MyProg.exe", "arguments")

To run your program when an Events cell gets evaluated, put the formula in the Events cell for the event that you want to trigger your program.

figure 26-5. events section in a shapesheet window.

Figure 26-5 Events section in a ShapeSheet window.

For example, to run a VBA macro when the user drops a particular master in a drawing, put a formula such as the following in the EventDrop cell in the Events section of the master:

 = CALLTHIS("Layout")

To run a VBA macro when a user double-clicks a particular shape, put the same formula in the EventDblClick cell in the Events section of the shape. Or set the double-click event for a particular shape by selecting a macro from the Run macro list on the Double-Click tab in the Behavior dialog box (on the Format menu, click Behavior).

Figure 26-6. Double-Click tab in the Behavior dialog box.

Figure 26-6 Double-Click tab in the Behavior dialog box.

For details about responding to events in the Events section, see Chapter 7, Enhancing Shape Behavior.

Running a program when the user chooses a menu command or toolbar button

You can add your own menu command or toolbar item to the Visio user interface and use it to run your program. For details, see Chapter 22, Customizing the Visio User Interface.

If you've created a toolbar button using the command bar object model and you want to load a COM add-in when a user clicks the button, you can use the OnAction property. (Setting the OnAction property allows Visio to load a COM add-in in response to a user clicking on a toolbar or menu item.) The syntax for setting the OnAction property for a COM add-in is:

 ctlButton.OnAction = "!<ProgID>"

where ctlButton is the CommandBarButton object and ProgID is the programmatic identifier for the add-in. The programmatic identifier is the subkey that is created for the add-in in the Windows registry. You must set the OnAction property for any COM add-in you create that is loaded on demand. For more details on implementing COM add-ins, see Chapter 23, Using COM Add-ins in a Visio Solution.

You can also use the OnAction property to run a VBA macro or a Visio add-on VSL in response to a user clicking on a toolbar or menu item. You can set the OnAction property for a VBA macro or Visio add-on using the following syntax:

 ctlButton.OnAction = "<ProjectName>!<MacroName>"

 ctlButton.OnAction = "<MacroName|AddOnName|VBACode>"

For example:

 'Runs the Hello World macro in the ThisDocument module 'of the Drawing1 project. Drawing1.vsd must be open. MyCtlButton.OnAction = "Drawing1!ThisDocument.HelloWorld" 'Runs the Hello World macro in the active document. MyCtlButton.OnAction = "ThisDocument.HelloWorld" 'Runs a Visio add-on named "My Organization Chart". 'Visio automatically looks at the Parameter property 'of the control to determine add-on arguments, if any. MyCtlButton.OnAction = "My Organization Chart" MyCtlButton.Parameter = "/FILENAME ""C:\Samples\My _     Organization Chart Data.xls"""

For more details on working with command bars, see Chapter 22, Customizing the Visio User Interface.

Note

To use the OnAction property in VBA or Visual Basic, you must set a reference to the Microsoft Office 10.0 object library.

Running VBA code inside of event-handling procedures

You can run VBA code by writing it in the ThisDocument class module under the appropriate event procedure. For example, to execute code when a document is opened, enter your code in the event procedure DocumentOpened.

Here are a few commonly handled document events: BeforeDocumentClose, BeforePageDelete, BeforeShapeDelete, BeforeSelDelete (before a set of shapes is deleted), ShapeAdded, DocumentCreated, DocumentOpened, DocumentSaved, and DocumentSavedAs.

For details about responding to object events, see Chapter 21, Handling Visio Events.