Changes in the RUNADDON Function and the AddOnName Property for 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.

Susan Harney
Microsoft Corporation

December 2002

Applies to:

   Microsoft Visio Professional 2002 SR-1
   Microsoft Visio Standard 2002 SR-1
   Microsoft Visio Professional 2002
   Microsoft Visio Standard 2002

Summary: Discover the changes made to the Visio RUNADDON function and the AddOnName property, including how to properly call them in code. (8 printed pages)

Contents

Introduction
Changes to the RUNADDON Function and AddOnName Property in Visio 2002
Using RUNADDON and AddOnName in Visio 2002
Summary of Calling Visio Add-ons and VBA Code, and Loading COM Add-ins, from ShapeSheet Cells and Menu or Toolbar Items
Additional Resources

Introduction

In Microsoft® Visio® 2002, changes were made to the RUNADDON function and the AddOnName property—specifically, you can no longer pass inline Microsoft Visual Basic® for Applications (VBA) code to RUNADDON or AddOnName.

This article reveals how RUNADDON and AddOnName behave differently in Visio 2002 than in earlier versions, and ways to use RUNADDON and AddonName.

**Note    **In addition to the change described above, Visio add-ons used with Visio 2002 must be installed in the Visio Start-up or Add-ons path defined in the application (on the Tools menu, click Options, and then click the File Paths tab in the Options dialog box). For more information about Visio add-ons, see the About Visio Add-ons and COM Add-ins article.

About extending solutions in Visio 2002

The Microsoft Visio 2002 platform provides multiple ways to programmatically extend your Visio solutions—Visio add-ons, COM add-ins (new in Visio 2002), or Microsoft Visual Basic for Applications (VBA) code that is stored in your Visio document.

The RUNADDON function and the AddOnName property are important because they provide an easy way to call your code from a ShapeSheet® cell, or in response to a user selecting a particular menu, toolbar, or accelerator item.

For more information about creating Visio add-ons and COM add-ins, see the About Visio Add-ons and COM Add-ins article.

Changes to the RUNADDON Function and AddOnName Property in Visio 2002

If you have created Visio solutions that passed inline Visual Basic code to the RUNADDON function or AddOnName property using earlier versions of Visio, you may have encountered the effects of the changes described previously — your solution code may not work in Visio 2002 as it did before.

This section provides details of how RUNADDON and AddonName work in Visio 2002 in contrast to earlier behavior.

RUNADDON function

The RUNADDON function calls a Visio add-on or a macro in the VBA project of a Visio document using the following syntax:

=RUNADDON("string")

RUNADDON tells Visual Basic to treat string as the name of a macro (optionally qualified with reference and module names). If the targeted VBA project doesn't recognize the string as the name of a macro, it treats the string as the name of an add-on to invoke.

If you attempt to pass code to the RUNADDON function that Visio does not recognize as either a macro name or the name of an add-on, nothing happens and the cell's formula evaluates to 0 (zero).

Note The changes made in Visio 2002 prevent the RUNADDON function from accepting arbitrary VBA code as an argument, or accepting calls to procedures with arguments. For details about using RUNADDON to call code in Visio 2002, see Calling code from RUNADDON and AddOnName later in this article.

AddOnName property

The AddOnName property gets or sets the name of a Visio add-on or procedure to run when its associated menu, toolbar, or accelerator is selected. To set the value of AddOnName, use the following syntax:

vsoObject.AddOnName = string

AddOnName tells Visual Basic to treat string as a procedure name (optionally qualified with reference and module names) followed by zero (0) or more arguments. If the targeted VBA project doesn't recognize the string as the name of a macro or a procedure with arguments, it treats the string as the name of an add-on to invoke.

If you attempt to pass code to the AddOnName property that Visio does not recognize as either a procedure or the name of an add-on, nothing happens and the menu item or toolbar item remains dimmed.

Note The changes made in Visio 2002 prevent the AddOnName property from executing arbitrary VBA code—the menu or toolbar item is dimmed in the user interface. For details about using AddOnName to call code in Visio 2002, see the following section.

Using RUNADDON and AddOnName in Visio 2002

This section describes the various ways in which you can trigger your code using the RUNADDON function and the AddOnName property. It also describes additional ways to call code from a ShapeSheet cell or menu item, along with suggestions for developers who have previously used RUNADDON or AddOnName to call code in another document's project or to queue marker events.

Calling code from RUNADDON and AddOnName

You can trigger code from the RUNADDON function and the AddOnName property in the following ways.

• Place code into a macro and call it from RUNADDON or AddOnName, or place code into a macro or procedure and call it from AddonName. For example:

  =RUNADDON("projectName.moduleName.macroName") or
  vsoMenuItem.AddOnName = ("projectName.moduleName.procName",
   "arg1", "arg2")
  

  If projectName is not explicitly provided, Visual Basic searches the document project that made the call.

  In the case of RUNADDON, you can call an add-on or a macro in a Visio document project.

  In the case of AddOnName, you can call an add-on, macro, or a procedure containing arguments.

• Use the CALLTHIS function to call a procedure with arguments from a ShapeSheet cell.

  For example:

  =CALLTHIS ("moduleName.procedureName","projectName",
  "arg1",arg2"…)
  

  Visio scans all open documents for the one containing projectName and calls procedureName in that project. If projectName is omitted or null (""), projectName is assumed to be in the Visual Basic project of the document that contains the CALLTHIS formula being evaluated.

  The CALLTHIS function is a good alternative for developers who previously used the RUNADDON function to call into procedures with arguments. You can only use CALLTHIS from a ShapeSheet cell, however, not from a menu or toolbar item. You cannot use CALLTHIS to launch a Visio add-on.

  Since the CALLTHIS function passes a reference to the shape that owns the formula being evaluated, code that is called from the CALLTHIS function has a signature that takes a Visio Shape object. For more information about CALLTHIS, see the Microsoft Visio ShapeSheet Reference.

• Implement your code in a COM add-in.

  If you are using the command bars object model, use the OnAction property of selected command bar objects to load your add-in if it has not already been loaded. Once your COM add-in is loaded you can listen to the Click event fired by the CommandBarButton object to trigger your code.

  If you are using the UIObject object model, you can fire marker events to a COM add-in using the AddonName property and the QueueMarkerEvent add-on that was included with Visio 2002 SR-1. You can also use this add-on to fire marker events to your COM add-in from a ShapeSheet cell using the RUNADDONWARGS function.

  For more information about the QueueMarkerEvent add-on, see the Using the QueueMarkerEvent Add-on in Visio Solutions article. For more information about command bars and the OnAction property, see the Microsoft Office type library.

Special considerations when calling code in another document

If your solution code is contained in a document project other than the one making the call, you can handle it in either of the following ways:

• In the project that contains the call, create a reference to the project that contains the code and pass the name of that project as an argument to RUNADDON and AddOnName.

  The RUNADDON function and the AddOnName property require you to have a reference to the other project in the project that is making the call. You can establish the reference either through the user interface (in the Visual Basic Editor, on the Tools menu, click References, and then from the list of Available References choose the name of the project that contains the code you want to call), or programmatically.

  To programmatically establish a project reference, use the Visio Application object's VBE property to access the Visual Basic projects associated with currently open Visio documents. You can then navigate through the Visual Basic object model to create a project reference.

Note By setting a reference in your project to the VBIDE type library you can take advantage of IntelliSense® technology and early binding in your code.

• If you are calling code from a ShapeSheet cell, you can use the CALLTHIS function described earlier in the Calling code from RUNADDON and AddOnName section.

  CALLTHIS does not require an explicit reference in the project containing the call to the project containing the code. You can only use CALLTHIS from a ShapeSheet cell, however, not from a menu or toolbar item. And you cannot use CALLTHIS to launch a Visio add-on.

  Since the CALLTHIS function passes a reference to the shape that owns the formula being evaluated, code that is called from CALLTHIS has a signature that takes a Visio Shape object. For more information on the CALLTHIS function, see the Microsoft Microsoft Visio ShapeSheet Reference.

Queuing marker events

Marker events were added to the Visio object model in Visio 5.0 to give developers the ability to distinguish Visio marker events from those caused by their own add-ons and add-ins.

In Visio 2002, you can use either of the following techniques to queue marker events using the RUNADDONWARGS function or the AddOnName property:

• Use the QueueMarkerEvent add-on included with Visio 2002 SR-1

  For example:

  =RUNADDONWARGS("QueueMarkerEvent","context string")
  

  If you are calling QueueMarkerEvent from AddOnName, pass the context string in the AddOnArgs property. For example:

  vsoMenu.AddOnName = "QueueMarkerEvent"
  vsoMenu.AddOnArgs = "context string"
  

  The add-on named QueueMarkerEvent runs in the Visio process and queues a marker event with a context string that matches the arguments it receives from the RUNADDONWARGS or AddOnName call. This add-on is not displayed in the user interface and its name is never translated.

  Download Visio 2002 SR-1 from the Microsoft Office Download Center.

**Note    **The QueueMarkerEvent add-on also enables you to notify COM add-ins from ShapeSheet cells, menu, toolbar, and accelerator items. For more information about the QueueMarkerEvent add-on, see the Using the QueueMarkerEvent Add-on in Visio Solutions article.

• Use the QueueMarkerEvent code in a macro

  Place the code that invokes the QueueMarkerEvent method in a macro in your document's Visual Basic project, and then call that macro using RUNADDON or AddOnName.

  Although this means having code in your document's Visual Basic project, the code is often generic and easily maintained. It is a good alternative if upgrading to Visio 2002 SR-1 is not possible.

Summary of Calling Visio Add-ons and VBA Code, and Loading COM Add-ins, from ShapeSheet Cells and Menu or Toolbar Items

Table 1. Options for calling code from a ShapeSheet cell

1The projectName is optional for all cases dealing with VBA macros, subs, or functions. If it is not specified, macroName is assumed to be in the VBA project of the document that contains the RUNADDON formula being evaluated. If you are calling into code in another project (for example, a stencil) projectName must be referenced by the document project that contains the RUNADDON call.

2The projectName is optional for all cases dealing with VBA macros, subs, or functions. If it is not specified, macroName is assumed to be in the VBA project of the document that contains the CALLTHIS formula being evaluated. The CALLTHIS function differs from the RUNADDON function in that a document's project doesn't need to reference another project in order to call into that project.

Table 2. Options for calling code or loading a COM add-in from a menu or toolbar item

1The OnAction property uses a different syntax for VBA macros: an exclamation point (!) between projectName and moduleName, rather than a period (.).

2When using the OnAction or AddOnName property to call an add-on, use the AddOnArgs property to specify arguments to send to the add-on when it is run.

Additional Resources

• For more information about the CALLTHIS, RUNADDON, and RUNADDONWARGS functions, see the Microsoft Visio ShapeSheet Reference in the Visio SDK.
• For more information about the AddOnArgs, AddOnName, AddOnPaths, OnAction, StartupPaths, and VBE properties, see the Microsoft Visio Automation Reference. This reference also contains information about the QueueMarkerEvent method and MarkerEvent event topics.
• For more information about Visio add-ons and COM add-ins, see the About Visio Add-ons and COM Add-ins article.
• For more information about the VBIDE type library, search for VBIDE type library.

Susan Harney is a technical writer who has been writing about the Visio developer platform for five years.