[Note: This is the first in a series of blog posts that will highlight some of the new members of the Visio OM that so far haven’t received a lot of fanfare.]

You might not be aware of the addition of a new method on the Page object to the Visio 2010 VBA API, Page.DropConnected, which makes it possible to add a shape to the drawing page and at the same time connect it to an existing shape on the page. You can specify the object to add to the page, which can be a Visio master, master shortcut, or 2-D shape, or any object that can be represented by an IDataObject object. You can also specify the existing shape on the page to which to connect the new shape, the direction from the existing shape in which to place the new shape, and the type of connector to use. Like the new shape itself, the connector can be a Visio master, master shortcut, or 2-D shape, or any object that can be represented by an IDataObject object.

The syntax for the new method looks like this:

Page.DropConnected(ObjectToDrop, TargetShape, PlacementDir, [Connector])

In the Help topic for this method, the parameters are described as follows:

• The ObjectToDrop parameter must be an object that references a two-dimensional (2-D) shape. If you pass a selection of shapes represented by an IDataObject object, Visio uses only the first of those shapes. If ObjectToDrop is not a valid Visio object, Visio returns an Invalid Parameter error. If ObjectToDrop is not a shape that matches the context of the method, Visio returns an Invalid Source error.
• The TargetShape parameter must be a 2-D top-level shape on the page. If TargetShape is invalid, Visio returns an Invalid Source error.
• The PlacementDir parameter value must be one of the VisAutoConnectDir constants. If you pass visAutoConnectDirNone for PlacementDir, Visio places the shape in a default location (0,0) and then connects it; the shape is not placed in relation to the target.
• The Connector parameter must be an object that references a one-dimensional (1-D) routable shape. If you pass a selection of shapes represented by an IDataObject object, Visio uses only the first of those shapes. If Connector is not a valid Visio object, Visio returns an Invalid Parameter error. If Connector is not a shape that matches the context of the method, Visio returns an Invalid Source error.

Note that the Connector parameter is optional. By specifying the PlacementDir parameter, you can place the new shape above, below, to the right, or to the left of the existing shape. The method returns the new shape as a Visio Shape object.

Here’s an example of how this process might look in the Visio UI. Say you have a circle shape on the page:

Let’s say you’d like to add a pentagon below the circle, connected to the circle by the default connector (a 2-D line), so that it would look like this:

To accomplish this, you can run the following VBA code :

Public Sub DropConnected_Example()

    Dim vsoShape As Visio.Shape
    Dim vsoMaster As Visio.Master
    Dim vsoMasters As Visio.Masters
    Dim vsoDocument As Visio.Document 

    Set vsoDocument = Visio.ActiveDocument
    Set vsoMasters = vsoDocument.Masters 
    Set vsoMaster = Application.Documents.Item("BASIC_U.VSS").Masters.ItemU("Pentagon")

    Set vsoShape = ActivePage.DropConnected(vsoMaster, ActivePage.Shapes("Circle"), visAutoConnectDirDown)

End Sub

This code assumes two things:

• That you have only a single circle shape on the page—if you have more, you’d have to be more specific about identifying the shape from which you want to connect.
• That you have the Basic Shapes (US Units) stencil open. Creating a new diagram from the Basic Diagram (US Units) template opens that stencil automatically.