Creating a Connected Drawing from a Program

You create a connected drawing from a program by dropping masters on a drawing page and then gluing the shapes together. Gluing is a directional operation, so it's important to know what you have glued to what. After shapes are glued, you can move a shape that has other shapes glued to it without breaking their connections, but not vice versa. This is true whether you move the shapes from a program or in a Microsoft® Visio® drawing window. For example, suppose a rectangle has a line glued to it. Moving the rectangle does not break the connection—the line remains glued to the rectangle and stretches as needed. However, moving the line breaks the connection.

This drawing demonstrates moving connected shapes. The line is glued to the rectangle (A). If you move the rectangle (B), these shapes remain connected. If you move the line (C), the connection breaks.

To glue shapes from a program

1. Decide what shape you want to glue to another shape, what the other shape is, and where to connect the shapes.

1. Get a Cell object that represents the part of the shape (such as an end point, control point, or edge of the shape) that you want to glue to.

1. Use the GlueTo method to specify a part of another shape (such as a connection point, vertex, or selection handle), or the GlueToPos method to specify a location, to create the connection between the shapes.

In this section…

What Can Be Glued to What

Gluing with Cell Objects

Gluing a Shape to Another Shape

What Can Be Glued to What

Only certain parts of shapes can be glued. For example, an endpoint of a one-dimensional (1-D) shape or a control handle of a two-dimensional (2-D) shape can be glued to a connection point, but a side of a 2-D shape can be glued to only a guide or guide point.

To use 1-D shapes to create a connected diagram, you glue the begin point and end point of each 1-D shape between two 2-D shapes, as shown in the following illustration.

Cell references for begin and end points of a 1-D shape

1. BeginX or BeginY

1. EndX or EndY

Another method for gluing one object to another is to create a master with a control handle that extends a line you can glue to another shape. As an example, the following illustration contains a shape that has a control handle that can be glued to another shape. The shape also has four named connection points, locations to which other shapes can be glued. The cell references you would use to glue these locations are shown in the following illustration.

Cell references for the control handle and connection points

1. Connections.top

1. Connections.left

1. Connections.right

1. Connections.bottom

1. Controls.X1

Gluing to part of a shape represented by a pair of cells

Many points on a shape—control handles, connection points, end points, geometry vertices, and so on—are specified by two ShapeSheet® cells, one for each of the x,y coordinates for the point. Whenever you glue to part of a shape represented by a pair of cells, you can specify either cell of the pair. For example, to indicate the first control handle on a shape, you can specify either Controls.X1 or Controls.Y1.

The following table lists the ShapeSheet cells that represent the parts of a shape you'll typically want to glue.

Typical cells for gluing parts of shapes

To glue this	Get one of these cells	And glue it to any of these cells in another shape
The begin point or end point of a 1-D shape	BeginX or BeginY EndX or EndY	Connections.Xi or Connections.Yi Geometry.Xi or Geometry.Yi AlignLeft, AlignCenter, AlignRight, AlignTop, AlignMiddle, or AlignBottom Angle PinX or PinY (to glue dynamically)
A control handle	Controls.Xi or Controls.Yi	Connections.Xi or Connections.Yi Geometry.Xi or Geometry.Yi AlignLeft, AlignCenter, AlignRight, AlignTop, AlignMiddle, or AlignBottom PinX or PinY
The edge of a shape	AlignLeft, AlignCenter, AlignRight, AlignTop, AlignMiddle, or AlignBottom	Angle

For other details, see the FromCell and ToCell properties in the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

Gluing to a selection handle

An alignment cell corresponds to the selection handle in the middle of the specified part of the shape. For example, AlignTop corresponds to the selection handle in the middle of the shape's top edge. Gluing to an alignment cell in a program is the same as gluing to the corresponding selection handle on the shape in a drawing window.

You don't actually glue to the selection handle itself—instead, you use the selection handle to create a connection point at that location on the shape. This is true whether you're gluing the shapes from a program or in a Visio drawing window. A row is added to the shape's Connections section to represent the new connection point.

Gluing to a guide or guide point

A guide is a line dragged out from a ruler in the Visio drawing window that you can use to align shapes. You can glue shapes to a guide, and then move the guide and the shapes with it. When you glue a 1-D shape to a guide, you can specify any cell in the guide. For example:

1DShp.Cells("BeginX").GlueTo GuideShp.Cells("PinX") 2DShp.Cells("AlignLeft").GlueTo GuideShp.Cells("PinX")

TOP

Gluing with Cell Objects

Once you've decided which part of the shape you want to glue to another shape, you get a Cell object that represents that part of the shape. To get a Cell object, get the Cells property of a Shape object and specify the name of the cell you want. For example, the following statement gets a Cell object that represents the x-coordinate of the first control handle of the shape represented by shpObj1:

Set celObj = shpObj1.Cells("Controls.X1")

If a point on a shape is represented by a pair of cells, you can specify only one cell of the pair. It doesn't matter which cell you specify. In the example above, Controls.Y1 would work equally well.

For details about working with Cell objects, see Chapter 17, Automating Formulas.

TOP

Gluing a Shape to Another Shape

You can use the GlueTo or GlueToPos method of a Cell object to glue a shape to another shape. With the GlueTo method, you specify a cell reference to a part of the other shape; the method then sets the formula of the Cell object to that cell reference. With the GlueToPos method, you specify a pair of decimal fractions relative to the other shape's width-height box. GlueTo or GlueToPos creates a connection point at that part of the shape or that location.

For example, the following statement uses GlueTo to glue the part of a shape represented by celObj—the control handle shown in the following illustration—to the shape represented by shpObj2, at that shape's fourth connection point, which has been renamed to Connections.bottom to create a more meaningful connection name.

celObj.GlueTo shpObj2.Cells("Connections.bottom")

Gluing a control handle to a connection point with the GlueTo method

1. celObj represents the control handle Controls.X1 of shpObj1

1. *celObj.*GlueTo shpObj2.Cells("Connections.bottom") glues the control handle of shpObj1 to the connection point of shpObj2 that has been named "bottom"

The following statement uses GlueToPos to glue the same shape to the center of shpObj2, creating a new connection point at that location. The location is specified as decimal fractions of the shape's width-height box, not as x,y coordinates. These fractions can be negative or greater than 1 to create a connection point outside the shape's width-height box.

celObj.GlueToPos shpObj2, .5, .5

Gluing a control handle to a location with the GlueToPos method

1. celObj represents the control handle Controls.X1 of shpObj1

1. GlueToPos*(shpObj2,.5,.5)* glues the control handle of shpObj1 to the center of shpObj2

Note To dynamically glue your shape, use the GlueTo method with the PinX or PinY cell as the cell you want to glue to. Gluing to PinX indicates a horizontal walking preference, and gluing to PinY indicates a vertical walking preference. All other cell references default to static glue. For details about static and dynamic glue, search the Microsoft Visio Help (on the Help menu, click Microsoft Visio Help).