Edited by Nina Miller

Figure 1 - Visio Control in a Windows Form

Introduction

One of the most powerful drawing tools on the market is Microsoft Visio for Office. However, if you want to create add-ins or applications for this tool, the documentation for controlling the API is scarce and hard to follow. Searching the Net for samples on using Visio inside of the ActiveX control can be daunting. It's even hard finding samples on how to do basic tasks, like drawing a shape inside the control. As a result, I decided to write my own sample that will help you get started drawing shapes in a Windows form using the Visio ActiveX Component. The sample will show you how to add the control to your toolbox, add a stencil, and connect two shapes together from the stencil.

***Note: If you are wondering: "How can I use the ActiveX control without Visio installed?", you can't. You need to have Visio installed on your machine in order to use the ActiveX control which means you need to own Visio. (I know this seems obvious to many reading this article, but I often get this question for other office products such as Microsoft Word and Microsoft Excel.) The ActiveX control does not stand alone, it talks directly to Visio through In-Place editing.

Installing in the Toolbox

To install the Visio ActiveX control into the tool box, simply right click on the Toolbox and pick ("Choose Items"). Then go to the COM tab as shown in figure 2 and select the Visio Active X Control, then click OK.

Figure 2 - Choosing the Visio COM componnet

This will install the Visio Component into your .NET Toolbox as shown in Figure 3:

Figure 3 - Visio Component inside the .NET Toolbox

Now you can simply drag the Visio control onto the Windows form as seen in figure 1.  We are now ready to program Visio in .NET.

Code

Like other office automation objects, Visio consists of an Application, Documents, and Windows. The document contains the shape data, and the window lets you trap window events and do view operations such as copy and paste. We will be working with two documents in Visio: (1) the stencil and (2) the page document. The stencil contains the shapes we want to draw to the page document. The Visio ActiveX control already provides us with an active document through the first page. However, the stencil document needs to be opened. We can use the OpenEx method in order to open an existing stencil. In this example, we open the Basic Shapes stencil. We then display the number of shapes in this stencil in our tool strip status bar.

The first shape we want to create in our page document is the triangle shape. All shapes are accessed through the Masters collection inside the stencil document. We use the Drop method to drop the triangle shape into the Visio Page. In the drop method we can specify where we want the shape to appear on the page. Coordinates in Visio start in the bottom left hand corner and are measured in inches. In this example, we drop a triangle on the lower left hand corner of the page at x=1.5", y=1.5". Next we drop a square in the upper right hand corner using the same Drop method at x=10", y=7.5".  (Note that the control is shown in landscape.)

Listing 1 - Drawing Shapes through Automation in the Visio Control

Connecting Shapes

Finally, we want to connect the two shapes together. This is accomplished through a property in Visio Shape objects called Cells. Cells are properties inside a shape used for a particular purpose to manipulate the shape or query the shape. The closest analogy to the concept of a Cell is that of a Cell in an Excel SpreadSheet. The Cell is accessed from three levels: a section, then a row, and finally, a cell which represents a property inside a Visio Shape. The get_cellSRC method of a Visio Shape allows you to access a Visio Connector Cell using  these three parameters. In this specific example we use: (1) the VisSectionIndices.visSectionObject enum (2) the VisRowIndices.visRowXFormOut enum, and (3) the VisCellIndices.visXFormPinX enum to access cell connectors of our triangle and square shapes. There appears to be some rhyme or reason to the naming of the row and the cell enumeration. Rows start with visRow<property group>. Cells start with vis<property group><sub property>.

The way to connect two shapes together in Visio is to drop the connector shape on the diagram and then use the Cells to "glue" the shapes to the connector. The GlueTo method of a Cell will glue the connector Cell of one shape to another shape's connector Cell.

Listing 2 -

The three sets of a parameters can be used in other ways to manipulate a shape. If we want to add an arrow to our connector, we can access three magic parameters to retrieve the cell that changes the arrow as shown in listing 3. Here we assign the FormulaU property in order to specify the shape of the arrow. You can experiment with other numbers to see what other arrows are produced. For example, while "5" produces a filled in arrow, "7" produces an arrow consisting of two lines.

Listing 3 - Adding an arrow to the connector

Likewise, we would arrive at the same result by getting the cell directly from the set of cells in the connector shape itself.  We just need to know the name of the property index string containing the end arrow:

Visio is a great drawing tool for creating everything from landscapes to CAD diagrams. Automating Visio can be accomplished with .NET through the COM Wrapper around the Visio ActiveX Control. Controlling Visio is a bit tricky, because you need to be aware of the properties that exist with Shapes and how to use them. As you become familiar with shapes and their properties, you can make Visio behave the way you wish within the boundaries of the Visio object model. Anyway, enjoy experimenting with the Visio Automation engine. Perhaps with the power of .NET and Visio you can create your own powerful product to draw in some customers for your own business.