Using the QueueMarkerEvent Add-on in Visio Solutions
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 Visio Standard 2002 SR1
Microsoft Visio Professional 2002 SR1
Summary: Fire marker events in response to user actions for solutions written in VBA, COM add-ins, or Visio add-ons listening to the marker event. (5 printed pages)
What the QueueMarkerEvent Add-on Does
Where to Find the QueueMarkerEvent Add-on
How to Use the QueueMarkerEvent Add-on
This article describes how to use the QueueMarkerEvent add-on to queue marker events within your Microsoft®** Visio® solutions. Like any Visio add-on, the QueueMarkerEvent add-on can be called from ShapeSheet® cells, menu or toolbar items implemented using the Visio **UIObject or CommandBar objects, persistent events, or other add-ons using the Application.Addons.Item property. The QueueMarkerEvent add-on allows developers to create shapes, menus and templates that, with the help of the add-on, fire marker events in response to user actions. Solutions listening to marker events can then respond to those events and react appropriately. This is especially important for COM add-ins, as they cannot be notified of many of these user actions in any other way.
In the following sections, you will learn what the QueueMarkerEvent add-on does, where to find it, and how to use it from an Event or Action cell in the ShapeSheet, from menu and toolbar items, and with persistent events.
What the QueueMarkerEvent Add-on Does
The QueueMarkerEvent add-on lets developers use COM add-ins, add-ons, and Microsoft Visual Basic®** for Applications **(VBA) code to make Visio notify their solution of the following user actions:
- Selection of menu items, toolbar items, and accelerator items implemented using the UIObject object or CommandBar objects
- User actions that causes a persisted event to be fired
- User actions that cause an Action or Event cell in the ShapeSheet to be evaluated
Any type of Visio solution (COM add-in, add-on or VBA code) can use the QueueMarkerEvent add-on. However, the add-on is especially useful for a COM add-in because it expands the range of actions to which a COM add-in can respond within a Visio solution.
When the QueueMarkerEvent Add-on is run, it calls the QueueMarkerEvent method on the Application object. The command line passed to the add-on by Visio is used as the argument for the QueueMarkerEvent method. This string includes any context strings provided by your solution as well as context information added by Visio.
Where to Find the QueueMarkerEvent Add-on
The QueueMarkerEvent add-on is provided in Visio Standard 2002 Service Release 1 (SR-1) or the Visio Professional 2002 Service Release 1 (SR-1) updates. You can download the Visio Standard 2002 SR-1 or the Visio Professional 2002 SR-1 updates from the Microsoft Download Center.
The QueueMarkerEvent add-on is implemented as an in-process add-on with the VAO_AOATTS_DONTSHOW attribute, which means that it does not appear on the Macros submenu (Tools menu) or on the Add-Ons submenu (if Visio is running in developer mode). However, this does not mean that the QueueMarkerEvent add-on is not available. You can see if the QueueMarker add-on is available by accessing it by name through the Application.Addons.Item method or using the Persist Events tool in the Microsoft Visio 2002 Software Development Kit (SDK), available from the Microsoft Download Center.
How to Use the QueueMarkerEvent Add-on
The QueueMarkerEvent add-on can be invoked from:
- ShapeSheet Action and Event cells using the RUNADDONWARGS function.
- Menu items, toolbar items, or accelerators using the Visio UIObject object.
- Menu items, toolbar items, or accelerators using the Visio CommandBar object.
- Persisted events using an Event object added to the document's EventList collection.
The Changes in the RUNADDON Function and the AddOnName Property for Visio 2002 article describes how to run add-ons, add-ins, and VBA from command bars, ShapeSheet, or the UIObject object.
Solutions that Use the Add-on Must Listen to Marker Events
Solutions that use the QueueMarkerEvent add-on must be listening to marker events (which are sourced by the Application object) before a marker event is queued. COM add-ins that need to respond to marker events created by this add-on should be loaded on startup (or by demand) and should initialize their event handling as part of the load process.
Visio solutions can handle events by:
- Using code-behind events (connection points, or WithEvents in Visual Basic)
- Creating an implementation of the IVisEventProc interface and using the AddAdvise method of the EventList object. The Visio internal event handling then calls this IVisEventProc implementation when events registered through the AddAdvise method occur.
Using AddAdvise with an implementation of the IVisEventProc interface often performs better than IConnectionPoint events, because your solution is only notified of events it registers for via the AddAdvise method.
For an example of a COM add-in that listens to marker Events using Event Objects and AddAdvise, see the Flowchart sample in the Microsoft Visio 2002 SDK.
Passing a String to the Add-on to Create Identifiable Marker Events
The QueueMarkerEvent add-on takes a single argument that is included at the end of the context string for the queued marker event. Additional information may be prepended to this string depending on how the add-on was called.
The context string passed to the add-on should identify the solution and the user action that caused the QueueMarkerEvent Add-on to be called. For example, you can use a context string such as:
A COM add-in receiving a marker event with this context string parses the string to determine if it needs to handle the marker event and what action caused the event to be queued. The solutionID argument identifies the solution and should be a string such as "CompanyName.SolutionName" or if your solution involves a COM add-in, use its Program or Class ID. Use the solutionID to determine if this marker event applies to your solution. The cmdID argument indicates what action the solution should take and should be a number with a corresponding constant defined in your solution.
The formatting of the suggested string matches that of Visio-generated command-line strings. Following this format makes it easier to parse and extract all relevant information from the context string.
Using the QueueMarkerEvent Add-on from a ShapeSheet Cell
To use the QueueMarkerEvent add-on from an Event or Action cell in the ShapeSheet, specify the QueueMarkerEvent add-on and the solution-specific context string in a formula as arguments to the RUNADDONWARGS function. For example:
RUNADDONWARGS("QueueMarkerEvent", "/soln=CompanyName.Demo /cmd=1")
Because the add-on is called from the ShapeSheet, Visio prepends information to the command-line string passed to the add-on. That additional information can be used to identify the shape, master, or style that contained the cell. For example, if the preceding formula was contained in a shape with NameID Sheet.1 on a page with index 1 in a document with index 1, then Visio would prepend the following string to the command-line string passed to the add-on:
/doc=1 /page=1 /shape=Sheet.1
The marker event created by the add-on would have the following context string:
/doc=1 /page=1 /shape=Sheet.1 /soln=CompanyName.Demo /cmd=1
Using the QueueMarkerEvent Add-on from Menu and Toolbar Items
For menu items, toolbar items, and accelerators implemented with the Visio UIObject object, the QueueMarkerEvent add-on can be assigned to the AddonName property for that item. The context string is passed to the QueueMarkerEvent add-on using the AddonArgs property. The following code demonstrates how to queue a marker event from a menu item:
Public Sub AddMenuExample() ' This procedure demonstrates how to queue a marker event from a menu item. ' ' Parameters ' vsoUIObject The Visio UIObject object ' vsoMenuSets The collection of menu sets ' vsoMenuSet The drawing window menu set ' vsoMenus The menu collection for the drawing window menu set ' vsoMenu The menu used for demonstration ' vsoMenuItems The collection of items in the menu ' vsoMenuItem The new menu item added to the collection Dim vsoUIObject As Visio.UIObject Dim vsoMenuSets As Visio.MenuSets Dim vsoMenuSet As Visio.MenuSet Dim vsoMenus As Visio.Menus Dim vsoMenu As Visio.Menu Dim vsoMenuItems As Visio.MenuItems Dim vsoMenuItem As Visio.MenuItem On Error GoTo AddMenuExample_Err 'Get a UIObject object that represents Microsoft Visio 'built-in menus. Set vsoUIObject = Visio.Application.BuiltInMenus 'Get the MenuSets collection. Set vsoMenuSets = vsoUIObject.MenuSets 'Get the drawing window menu set. Set vsoMenuSet = vsoMenuSets.ItemAtID( _ visUIObjSetDrawing) 'Get the Menus collection. Set vsoMenus = vsoMenuSet.Menus 'Add a Demo menu before the Window menu. Set vsoMenu = vsoMenus.AddAt(7) vsoMenu.Caption = "Demo" 'Get the MenuItems collection. Set vsoMenuItems = vsoMenu.MenuItems 'Add a menu item to the new Demo menu. Set vsoMenuItem = vsoMenuItems.Add 'Set the properties for the new menu item. vsoMenuItem.Caption = "Queue marker event" vsoMenuItem.AddOnName = "QueueMarkerEvent" vsoMenuItem.AddOnArgs = "/soln=Demo /cmd=2" vsoMenuItem.ActionText = "Queue marker event" 'Tell Visio to use the new UI when the document 'is active. ThisDocument.SetCustomMenus vsoUIObject Exit Sub AddMenuExample_Err: MsgBox Err.Description End Sub
This code creates a new menu called Demo, which appears to the left of the Window menu. The Demo menu contains a single menu item, Queue marker event. When the user clicks this menu item, the code queues a marker event with the context string:
Using the QueueMarkerEvent Add-on with Persistent Events
The QueueMarkerEvent add-on can also be used with persistent events by adding an Event object to the document's EventList collection. Persistent events can be stored with a document. This approach allows you to place code that responds to a document event without using an event handler for ThisDocument.
Sub CreatePersistentEvent() ' This procedure creates a persistent event for a document. ' ' Parameters ' vsoDocument The Visio document in which to create the ' persistent event. ' vsoEvent The persistent event to save with the document. ' strDrawingName The name of the drawing with the persistent ' event. Dim vsoDocument As Visio.Document Dim vsoEvent As Visio.Event Dim strDrawingName As String On Error GoTo CreatePersistentEvent_Err ' Create a new document. Set vsoDocument = Application.Documents.Add("") ' Add an Event object to the document's EventList collection. Set vsoEvent = vsoDocument.EventList.Add( _ visEvtCodeDocOpen, visActCodeRunAddon, _ "QueueMarkerEvent", "/soln=Demo /cmd=2") ' Name, save, and close the document with the ' persistent event. strDrawingName = "NewDrawing.vsd" vsoDocument.SaveAs strDrawingName vsoDocument.Close Set vsoDocument = Nothing Exit Sub CreatePersistentEvent_Err: MsgBox Err.Description End Sub
Running this code creates a new Visio document named NewDrawing.vsd. This document contains a persistent event that calls the QueueMarkerEvent add-on to queue a marker event when the document is opened.
You can also create persistent events using the Persistent Events tool, available in the Visio 2002 SDK.
To learn more about the differences between Visio add-ons and COM add-ins, see the About Microsoft Visio Add-ons and COM Add-ins article.
To learn more about changes to the RUNADDON function and AddonName property in Visio 2002, see the Changes in the RUNADDON Function and the AddOnName Property for Visio 2002 article.
To learn more about marker events, see the following topics in the Microsoft Visio Automation Reference:
To learn more about Visio command strings, see Interpreting the Command String that Visio Sends to Your Program in Developing Microsoft Visio Solutions.
For an example of a COM add-in that responds to marker events but uses VBA code in a template for its queue marker events, see the Flowchart sample in the Microsoft Visio 2002 SDK, available from the Microsoft Download Center.
Note The Flowchart sample is only available in the SDK download and is not accessible from the online SDK.
Mark Bukovec is a freelance developer and technical writer. Previously, Mark worked at Microsoft for five years, most recently as a program manager with the COM+ group.