Using Automation in a Visio Solution

3 4

Some solutions require more than shapes, stencils, and templates. For example, you might need to create drawings based on data that changes from day to day, or perform routine shape development tasks over and over. You might support users who need to create drawings but don't want to become experts in Microsoft Visio, or you might use their drawings as a source of data for other purposes.

You can automate such tasks by using Automation to incorporate the functionality of the Visio engine in a solution, simply by using its objects.

If you're familiar with Microsoft Visual Basic for Applications (VBA), you use objects all the time—controls such as command buttons, user forms, databases, and fields. With Automation, you can use other applications' objects as well. Drawings, masters, shapes, and even the Visio menus and tools can become components of your programs. A program can run within a Visio instance or start the Visio application and then access the objects it needs.

Visio includes VBA, so you don't need to use a separate development environment to write your programs. However, you can write programs that control the Visio engine in any language that supports Automation. Most of the examples in this guide are in VBA, but the principles apply to any programming language.

Automation and Visio Objects

Automation is the means by which a program written in VBA, Microsoft Visual Basic, C/C++, or another programming language that supports Automation can incorporate the functionality of an application such as Visio, simply by using its objects.

In Automation, the application that provides the objects (sometimes called the Automation server) makes the objects accessible to other applications and provides the properties and methods that control them. (This is sometimes called exposing the objects.)

The application that uses the objects (such as your program, sometimes called the Automation client) creates instances of the objects and then sets their properties or invokes their methods to make the objects serve the application. The server application and client application interact by making function calls through the Automation libraries, which are installed when any application that supports Automation—such as Visio, Visual Basic, or Microsoft Windows—is installed.

Unlike a scripting language, which simply automates the same actions you would perform in an application's user interface—choosing menu commands, pressing keys, typing, and so on—Automation accesses the application's objects. An object encapsulates data, behavior, and events with an interface that allows you to access them. Each Visio object has properties (data), methods (behavior), and events that you can use to take advantage of that object's capabilities in your program.

Visio objects reside in a Visio instance—a VBA program runs within an instance of the Visio application and then accesses the objects it needs. An external program runs outside an instance of Visio, so it starts Visio or accesses a Visio instance that is already running. Then it accesses the Visio objects it needs. Most objects in the Visio object model correspond to items that you can see and select in a Visio instance. For example, a Page object represents a drawing page; a Shape object represents a shape in a drawing. A shape's formulas are represented by Cell objects.

Many chapters in this guide describe how to incorporate Automation into a Visio solution. For an introduction, see Chapter 14, Automation and the Visio Object Model.

Monitoring Events and Totaling Values: an Example

To see how a solution might use Automation to access Visio objects, consider a solution that monitors events that are triggered as shapes are added to or deleted from a drawing. The solution keeps a running total of the power consumption represented by each shape, to make sure it doesn't exceed an established limit.

Figure 1-9 A solution that monitors power consumption represented by shapes in a drawing.

The example starts with an initialization procedure that checks all of the shapes in an existing drawing. The limit value is the text of a shape named "Limit," which the user can type in the Limit shape on the drawing. (The VBA Val function converts the text to a Double that can be used in subsequent calculations.) The solution keeps the running total in a user-defined cell named "PC" in a shape named "Current."

Each shape representing a device that consumes power stores its power consumption value in a custom property named "PowerConsumption," which the program accesses through the Cells property of a Shape object. The program iterates through the Shapes collection of the Page object passed to the InitWith procedure, checking the power consumption value of each shape that has a PowerConsumption property. If the total power consumption exceeds the limit set for the drawing, the solution alerts the user by setting the Color cell in the Character Format section of the Limit shape (Char.Color) to 2, which changes the color of the shape's text to red.

 Option Explicit Private WithEvents thePage As Page Private theLimit As Double Private theCurrent As Cell Public Sub InitWith(aPage As Page)     Dim i As Integer     Set thePage = aPage     theLimit = Val(aPage.Shapes("Limit").Text)     Set theCurrent = aPage.Shapes("Current").Cells("User.PC")     theCurrent.ResultIU = 0#        For i = 1 To aPage.Shapes.Count         With aPage.Shapes(i)             If .CellExists("Prop.PowerConsumption", False) Then                 theCurrent.Result("") = _                     theCurrent.Result("") + _                         .Cells("prop.PowerConsumption").Result("")                 If theCurrent.Result("") > theLimit Then                     aPage.Shapes("Limit").Cells("Char.Color"). _                         Result("") = 2                         End If             End If         End With     Next i End Sub 

Suppose the user adds a shape to the drawing. This action triggers a ShapeAdded event, which is handled by the following event procedure in the solution. Like the page initialization procedure, it adds the power consumption value of the newly added shape to the total, and checks whether it exceeds the limit for the drawing.

 Private Sub thePage_ShapeAdded(ByVal Shape As Visio.IVShape)     If Shape.CellExists("Prop.PowerConsumption", False) Then         theCurrent.Result("") = theCurrent.Result("") + _             Shape.Cells("prop.PowerConsumption").Result("")         If theCurrent.Result("") > theLimit Then             thePage.Shapes("Limit").Cells("Char.Color").Result("") = 2         End If     End If End Sub 

Deleting a shape triggers a BeforeShapeDelete event. Although a solution cannot cancel the deletion, it can perform operations that require the shape to be present before it is actually removed from the drawing. The following event procedure subtracts the power consumption value of the deleted shape from the total to keep it current and, if deleting the shape brings the total under the limit, changes the color of the Limit shape's text back to black (0).

 Private Sub thePage_BeforeShapeDelete(ByVal Shape As Visio.IVShape)     If Shape.CellExists("Prop.PowerConsumption", False) Then         theCurrent.Result("") = theCurrent.Result("") - _             Shape.Cells("prop.PowerConsumption").Result("")         If theCurrent.Result("") <= theLimit Then             thePage.Shapes("Limit").Cells("Char.Color").Result("") = 0         End If     End If End Sub 

For details about accessing a shape's formulas through Automation, see Chapter 17, Automating Formulas. For details about handling Visio events in a solution, see Chapter 21, Handling Visio Events.