Automating Drawing with Masters

The most convenient means of creating shapes from a program is to drop masters from a stencil. A master is essentially ready to use in a drawing, requiring very little additional processing by your program. You can use masters from a stencil you develop and provide with your program or from any of the stencils provided with Microsoft® Visio®.

To drop a master on a page

1. Create a Document object that represents the stencil containing the master you want.

1. Create a Master object that represents that master.

1. Create a Page object that represents the drawing page where you want to drop the shape and drop the master onto the drawing page.

In this section…

Getting the Stencil

Getting the Master

Dropping the Master on the Page

Getting the Stencil

You can get a reference to any stencil that is already open by retrieving it from the Documents collection of the Application object. For example:

Set stnObj = Documents("Basic Shapes.vss")

The example uses the variable name stnObj rather than docObj to distinguish among the stencil and other kinds of files. This naming convention can prevent confusion later.

As with any file-related operation, it's prudent to make sure the stencil is actually available before attempting to use it. The Set statement above would return an error if Basic Shapes.vss was not open. To check for this, use the following code:

'If the file is not open, open it. On Error Resume Next 'Get a reference to the Stencil object. Set stnObj = Documents("Basic Shapes.vss") 'The stencil was not open, we need to open it. If stnObj = Nothing Then     'OpenEx could not open the file.     On Error Go To errorhandler     Set stnObj = Documents.OpenEx ("Basic Shapes.vss",visOpenRO) End If

Typically a stencil is opened as a read-only file to protect it from changes, but it's always possible for the user to open it as an original and alter its workspace or move or delete a file, which could affect which stencils are opened when the template is used.

TOP

Getting the Master

To get a reference to a master, you need to get the Masters collection of a stencil file that contains the master you want. A Document object has a Masters property that returns the Masters collection for a document's stencil. You can refer to a Master object by its name or by its index within the Masters collection. For example:

Set mastObj = stnObj.Masters("Star 5")

A common pitfall in this process is to get the Masters collection of the drawing file rather than that of the stencil file. Every Visio document has a stencil, which means that every Document object has a Masters collection. However, the Masters collection of a drawing file contains only the masters that have already been dropped onto the drawing; the Masters collection of a new document is usually empty. In either of these cases, this particular Masters collection often won't contain the master you're trying to get. If your program fails to get a Master object, make sure you're getting it from the stencil file and not the drawing file.

TOP

Dropping the Master on the Page

To drop a master on the page, you first need to get the Page object that represents the drawing page, and then use the Drop method of the Page object. The Drop method is equivalent to dragging and dropping a shape with the mouse.

Drop takes three arguments: a reference to an object and a pair of coordinates. If the object being passed to the Drop method is a master, the coordinates indicate where to position the object's pin**on the drawing page. If the object being passed is an instance of a master, the pair of coordinates indicate the center of the object's width-height box.

Set pagObj = ThisDocument.Pages(1) Set shpObj = pagObj.Drop(mastObj, 4.25, 5.5)

Coordinates are measured from the lower-left corner of the page. In this example, 4.25, 5.5 positions the shape's pin in the center of an 81/2-in. by 11-in. drawing page in an unscaled drawing. (In a scaled drawing, you specify coordinates in drawing units expressed in inches. For example, if the drawing scale is 1 in. = 1 ft., you would specify the coordinates 51, 66 to drop the shape in the center of the page.) For details about shape coordinates, see Chapter 2, Creating Visio Shapes.

The shape's pin is positioned at the coordinates 4.25, 5.5 (A) specified with the Drop method.

For simplicity's sake, this example drops a single shape in the exact center of the drawing page, and uses constants to indicate its position. However, determining where to place shapes in a real-world drawing can be a challenge, especially in a connected diagram with more than a few shapes. For an example of one approach, see Placing Shapes in a Drawing later in this chapter.

In addition to dropping masters onto a drawing page, you can use the Drop method to:

• Make a shape from an existing shape.

• Add a shape to a group.

• Create a master on the fly by dropping a shape into a stencil (the stencil file must be open as Original, not Read only).

• Modify a master by dropping an object into an open master.

To drop multiple shapes, use the DropMany method, which is equivalent to dragging and dropping multiple shapes with the mouse.

Note When a program draws or drops a shape in a scaled drawing, it must convert the coordinates from drawing measurements to inches. For example, the following statement draws a rectangle from 3 ft, 4 ft to 5 ft, 6 ft on a drawing scaled in inches:

PagObj.DrawRectangle(36, 48, 60, 72)