Use the Page.DropCallout method to add callouts to shapes programmatically in Visio 2010

[Note: This is the fourth in a series of blog posts that highlight some of the new members of the Visio 2010 VBA object model.]

In the first post in this series, I talked about the Page.DropConnected method. In the second post, I featured the Page.LayoutChangeDirection method, which is another new method on the Page object of the Visio 2010 VBA object model that you might not yet have encountered. The Page.LayoutChangeDirection method makes it possible to rotate or flip a set of two or more connected shapes on the page as a unit, without having to rotate or flip the individual shapes. In the most recent post, I featured the Page.AutoConnectMany method, which you can use to automatically connect multiple shapes as you drop them on the drawing page.

This post focuses on yet another new method on the Page object, the Page.DropCallout method, which creates a new callout shape on the page and associates the callout with the target shape you specify.

The syntax for this method is as follows:

Page.DropCallout(ObjectToDrop As Unknown, TargetShape As Shape)

The DropCallout method operates on a Page object and takes two required parameters:

• ObjectToDrop, which represents the callout shape to use.  This parameter is specified as [Unknown], which means that you can pass a Master, MasterShortcut, Shape, or IDataObject object.
• TargetShape, which represents the existing shape on the page with which you want to associate the callout. If you don’t pass anything for this parameter, Visio puts the resulting callout at the center of the page and does not associate it with any shape in particular.

The method returns a Shape object that represents the callout added to the page.

The DropCallout method corresponds to the Callout command on the Insert tab in the Visio 2010 user interface:

When you click Callout, the Callout Gallery appears:

This gallery displays the various built-in callout shapes available in Visio 2010. When you pause the mouse over a callout shape, Visio both displays the name of the callout and previews its appearance. For example, here’s what the Word balloon callout looks like in preview:

It takes two steps to access these callout shapes programmatically:

1. First, you get the hidden stencil that contains them. To do so, you use the Application.GetBuiltInStencilFile method, passing it the constants visBuiltInStencilCallouts (from the VisBuiltInStencilTypes enumeration, to specify the hidden stencil that contains callouts), and visMSUS (from the VisMeasurementSystem enumeration, to specify US units, assuming those are the units you want).
2. Then you pass that hidden stencil to the Documents.OpenEx method, as well as the visOpenHidden constant (from the VisOpenSaveArgs enumeration, to specify that you don’t want to display the opened stencil in the stencil window).

In the example code that follows, both of these steps happen in the same line of code, as you will see.

Here’s an example of how the DropCallout method works. Suppose you have a blank Visio drawing and you want to first add a rectangle to the page and then add a Word balloon callout associated with the rectangle. Paste the following code into the Visual Basic Editor code window (to open it, press ALT+F11) and then run it:

Public Sub DropCallout_Example()

Dim vsoDocument As Visio.Document

Dim vsoTargetShape as Visio.Shape

Set vsoDocument = Application.Documents.OpenEx(Application.GetBuiltInStencilFile(visBuiltInStencilCallouts, visMSUS), visOpenHidden)

Set vsoTargetShape =  ActivePage.DrawRectangle(3, 4, 6, 7)

Application.ActivePage.DropCallout vsoDocument.Masters.ItemU("Word balloon"), vsoTargetShape

vsoDocument.Close

Your diagram should now look like this:

Additionally, you can access callout information about shapes and specify callout relationships between shapes by using three new properties on the Shape object:

• The CalloutsAssociated property returns an array of Long values that contains the collection of IDs of the callout shapes associated with a specified target shape, or nothing if there are no callout shapes associated with the shape.
• The CalloutTarget property gets or sets the target shape associated with a callout shape.
• The Boolean IsCallout property returns True if the shape it’s called on is a callout shape.