Using the QueueMarkerEvent Add-on in Visio Solutions

  • Article

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.

 

Mark Bukovec
December 2002

Applies to:
     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)

Contents

Introduction
What the QueueMarkerEvent Add-on Does
Where to Find the QueueMarkerEvent Add-on
How to Use the QueueMarkerEvent Add-on
Additional Resources

Introduction

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:

/soln=solutionID /cmd=cmdID

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:

"/soln=Demo /cmdID=2".

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.

Additional Resources

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.