Connect Object for a Control Handle to a Shape

More Connectivity API options

Use Shape.ConnectedShapes(Flags, CategoryFilter) to return an array of identifiers (IDs) of shapes that are one degree of separation away from the given shape (i.e. separated by a 1-D connector). In other words you no longer have to go through the connector to see what is on the other side. The IDs can be filtered as incoming or outgoing connections.

Try it! ConnectedShapes

1. 
   Open \Demos\Vol3\Getting Data from Drawings\Connections API.vsd.
   
2. 
   Select page ConnectedShapes and follow the directions on the page.
   
3. 
   Open the VBA Window (Alt—F11) and turn on display of the Immediate Window (View > Immediate Window). The results of running the macros are written to this window.
   

'Use Shape.ConnectedShapes to get the shapes that are incoming connections to a shape

Dim shp As Visio.Shape

Dim shpIDs() As Long

Dim i As Integer

If ActiveWindow.Selection.Count = 0 Then

MsgBox ("select a shape with connections")

Exit Sub

Set shp = ActiveWindow.Selection(1)

End If

shpIDs = shp.ConnectedShapes(visConnectedShapesIncomingNodes, "Square")

For i = 0 To UBound(shpIDs)

Debug.Print ActivePage.Shapes(shpIDs(i)).Name

Next

• 
  Flags: Filters the list of returned shape IDs by the directionality of the connectors.
  
• 
  CategoryFilter: Filters the list of returned shape IDs by limiting it to IDs of shapes that match the specified category. A shape’s categories can be found in the User.msvShapeCategories cell of its ShapeSheet. In the sample code above the method only returns shapes that are in the category “Square” which is designated in the shape’s User.msvShapeCategories cell.
  

Use Shape.GluedShapes(Flags, CategoryFilter, [pOtherConnectedShape]) to return an array of identifiers for the shapes that are glued to a shape. The returned IDs can be filtered by 1D vs. 2D and by incoming vs. outgoing connections. You can optionally specify another shape to which any returned shapes must also be glued.

Try it! GluedShapes

1. 
   Open \Demos\Vol3\Getting Data from Drawings\Connections API.vsd.
   
2. 
   Select page GluedShapes and follow the directions on the page.
   
3. 
   The results of running the macros are displayed in VBA’s Immediate window.
   

shpIDs = shp.GluedShapes(visGluedShapesIncoming1D, "")

Debug.Print "Incoming 1D shapes"

For i = 0 To UBound(shpIDs)

Debug.Print ActivePage.Shapes(shpIDs(i)).Name

Next

• 
  Flags: Specifies dimensionality and directionality of connectors of shapes returned.
  
• 
  CategoryFilter: Specifies category of shapes returned.
  
• 
  pOtherConnectedShape: Optional additional shape to which returned shapes must also be glued
  

A method that parallels the AutoConnect feature is Page.DropConnected(ObjectToDrop, TargetShape, PlacementDir, [Connector]). This creates a shape, positions it relative to the target shape and adds a connector from the target shape to the new shape. You can optionally specify a specific connector to use if you need to override the default connector.

Try it! DropConnected

1. 
   Open \Demos\Vol3\Getting Data from Drawings\Connections API.vsd.
   
2. 
   Select page DropConnected and follow the directions on the page. Six Process shapes are dropped and connected on the page.
   

'use Page.DropConnected to drop several Process shapes

Dim lastDrop As Visio.Shape

Dim i As Integer

Set lastDrop = ActivePage.Drop(ActiveDocument.Masters("Process"), 4.5, 8)

For i = 1 To 5

Set lastDrop = _

ActivePage.DropConnected(ActiveDocument.Masters("Process"), _

lastDrop, visAutoConnectDirDown)

Next

• 
  ObjectToDrop: The shape to be added to the page
  
• 
  TargetShape: The existing shape from which to align, space, and connect
  
• 
  PlacementDir: The direction from TargetShape in which to place ObjectToDrop . The example drops shapes using visAutoConnectDirDown.
  
• 
  Connector: The connector to use (optional). This overrides usage of the default Dynamic Connector.
  

To drop a new shape on a connector and split the connector, use Page.SplitConnector(ConnectorToSplit, Shape). Pass it the connector to split and the shape to drop.

Try it! SplitConnector

1. 
   Open \Demos\Vol3\Getting Data from Drawings\Connections API.vsd.
   
2. 
   Select page SplitConnector and follow the directions on the page. Shape 2 is inserted between shape 1 and shape 3 and the existing connector is split.
   

Set ovShape = ActiveWindow.Selection(2)

Set newConnector = ActivePage.SplitConnector(connector, ovShape)

• 
  ConnectorToSplit: The connector to split. Must be a routable 1-D connector.
  
• 
  Shape: The shape to use to split the connector. Must be a 2-D shape.
  

Connectors can be unglued and the end of the connector moved away from the original glue position with a single method call. Use Shape.Disconnect(ConnectorEnd, OffsetX, OffsetY, Units) and specify the end of the connector to disconnect, the offset, and the units.

Try it! Disconnect

1. 
   Open \Demos\Vol3\Getting Data from Drawings\Connections API.vsd.
   
2. 
   Select page GluedShapes and follow the directions on the page to run macro ShapeDisconnect. Both ends of the connector are unglued and moved away from the connection points by .25 inches in each direction.
   

ovShape.Disconnect visConnectorBothEnds, 0.25, 0.25, visInches

End If

• 
  ConnectorEnd: The end of the connector to disconnect
  
• 
  OffsetX: The x-distance that the connector end is moved away from the shape
  
• 
  OffsetY: The y-distance that the connector end is moved away from the shape
  
• 
  Units: The units of measure for the assigned offset values
  

To add many connections quickly, use Page.AutoConnectMany(FromShapeIDs(), ToShapeIDs(), PlacementDirs(), [Connector]). This method automatically draws multiple connections in the specified directions between the specified shapes. It returns the number of shapes connected.

Try it! AutoConnectMany

1. 
   Open \Demos\Vol3\Getting Data from Drawings\Connections API.vsd.
   
2. 
   Select page AutoConnectMany and follow the directions on the page. The selected shapes are connected and repositioned from left to right.
   

'use Page.AutoConnectMany to create connectors between shapes

If ActiveWindow.Selection.Count < 1 Then

MsgBox "Select at least two shapes in the order they are to be connected"

Exit Sub

End If

Dim toShapeIDs(10) As Long

Dim placementDirs(10) As Long

Dim i As Integer

For i = 1 To ActiveWindow.Selection.Count - 1

fromShapeIDs(i) = ActiveWindow.Selection(i).ID

toShapeIDs(i) = ActiveWindow.Selection(i + 1).ID

placementDirs(i) = visAutoConnectDirRight

Next

ActivePage.AutoConnectMany fromShapeIDs(), toShapeIDs(), placementDirs()

• 
  FromShapeIDs(): An array of identifers of the shapes from which to draw a connection
  
• 
  ToShapeIDs(): An array of identifers of the shapes to which to draw a connection
  
• 
  PlacementDirs(): An array of constants that represent the directions in which to draw the connection
  
• 
  Connector: The connector to use (optional). This overrides usage of the default Dynamic Connector.
  

Try it! DeleteEx

1. 
   Open \Demos\Vol3\Getting Data from Drawings\Connections API.vsd.
   
2. 
   Select page DeleteEx and follow the directions on the page. The selected shapes are connected and repositioned from left to right.
   

ovShape.DeleteEx VisDeleteFlags.visDeleteHealConnectors

• 
  Flag: can specify that unselected connectors, shapes within a container, or callouts are to also be deleted. The flag must be a bitwise combination of the following constants.
  
  • 
    visDeleteNormal=0 – match the deletion behavior that is in the user interface
    
  • 
    visDeleteHealConnectors=1 – delete connectors that are attached to deleted shapes
    
  • 
    visDeleteNoHealConnectors=2 – do not delete connectors that are attached to deleted shapes
    
  • 
    visDeleteNoContainerMembers=4 – do not delete unselected members of containers or lists
    
  • 
    visDeleteNoAssociatedCallouts=8 – do not delete unselected callouts that are associated with shapes