Getting and Releasing Visio Objects

3 4

You get an object by declaring an object variable, navigating through the object model to get a reference to the object you want to control, and assigning the reference to the object variable. Once you have a reference to an object, you can set and get the values of its properties or use methods that cause the object to perform actions.

Declaring Object Variables

A variable that stores a reference to a Visio object should be declared as a Visio object type such as Visio.Page or Visio.Document as defined in the Visio type library. Once you have gotten an object you want to control, use the Set statement to assign the reference to the object variable. You don't have to assign all object references to variables, but it's almost always a good idea, especially if your program refers to an object more than once. For example, most programs have at least one object variable to store a reference to the Page object that represents the page that your program will manipulate. The objects you reference depend on the purpose of your program. You can't store the value of an object variable between program executions.

A variable can be declared as the more general Object data type, but using Visio object types will increase the speed of your program as well as eliminate possible confusion or conflicts in object and property names when programming with other applications and Visio. For example, when declaring an object variable for a Visio page use the following syntax:

 Dim pageObj As Visio.Page 

You could eliminate Visio and just use Page, but other applications may have a Page object. For example, Microsoft Excel has a Cell object, as does Visio, but the two objects are different and cannot be used interchangeably. It is good practice to refer to the object and the application specifically.

You can declare a variable as local, module-level, or global. The scope you choose depends on how you plan to use the variable in your program. For complete details about declaring variables, see the Microsoft Visual Basic Help.

Accessing Visio Objects through Properties

Most Visio objects have properties whose values refer to other objects. You use these properties to navigate up and down the layers of the object model to get to the object you want to control.

Let's say the object you want to control is the Shape object. You first gain access to the object model through the top-level object, the Application object. The Documents property of an Application object returns a Documents collection. You would continue stepping through the object model in the following manner:

• The Documents property of an Application object returns a reference to the Documents collection.
• The Item property of a Documents collection returns a reference to a Document object.
• The Pages property of a Document object returns a reference to a Pages collection.
• The Item property of a Pages collection returns a reference to a Page object.
• The Shapes property of a Page object returns a reference to a Shapes collection.
• The Item property of a Shapes collection returns a reference to a Shapeobject.

Conversely, most objects have a property that refers to the object above it in the hierarchy, such as the Document property of a Page object, which returns a reference to the Document object that contains the Page object.

Referring to an Object in a Collection

A collection is an object that represents zero or more objects of a particular type. You can iterate through a collection to perform the same operation on all of its objects, or to get a reference to a particular object in the collection. Each collection has two properties you can use to refer to the objects in it:

• The Item property returns a reference to an object in the collection. This is the default property for most collections.
• The Count property returns the number of objects in the collection. For details about the Count property, see Iterating through a Collection later in this section.

The Item property takes a numeric argument that represents the object's index, or ordinal position, within the collection. The first item in most collections has an index of 1. For example, if a Document object's Index property returns 5, that Document object is the fifth member of its Documents collection.

The following collections, however, are indexed starting with zero (0) rather than 1: AccelTables, AccelItems, Colors, Hyperlinks, MenuSets, Menus, MenuItems, ToolbarSets, Toolbars, and ToolbarItems. If the Index property of an object in one of these collections returns 5, that object would be the sixth member of its collection.

To get an object by specifying its index, use code such as the following (where pagsObj represents a Pages collectionand shpsObj represents a Shapes collection):

 Set appObj = Visio.Application Set docsObj = appObj.Documents Set docObj = Documents.Item(1) Set pagsObj = docObj.Pages Set pagObj = pagsObj.Item(1) Set shpsObj = pagObj.Shapes Set shpObj = shpsObj.Item(1) 

Assuming at least one shape is on the page, this statement returns a reference to the first Shape object in the Shapes collection. If the collection is empty, this statement causes an error.

Tip

---

You might want to check the Count property of a collection before using Item, to make sure Count is not 0.

Figure 14-3 Shape object and related objects higher in the Visio object model.

For certain collections—Documents, Pages, Masters, Shapes, or Styles—the Item property can also take a string argument that specifies the object's name, which can be more convenient than referring to the object by its index. For example, the following code gets the Master object named 2-D Double in the Masters collection.

 Set mastObj = mastsObj("2-D Double") 

Iterating through a Collection

A collection's Count property returns the number of objects in the collection. If the Count property is zero (0), the collection is empty. For example, the following statement displays the number of documents that are open in a Visio instance:

 MsgBox "Open documents = " & Str$(Documents.Count) 

Most often, you'll use the Count property to set the limit for an iteration loop. Notice the use of Count in the For statement of the following example. The For loop iterates through a Documents collection, checking the last three characters of each Document object's file name. If the last three characters are vss or vsx (indicating that the document is a stencil), its name is added to the list in a combo box.

 Set docsObj = Application.Documents For i = 1 To docsObj.Count       Set docObj = docsObj.Item(i)       If UCase(Right(docObj.Name, 3)) = "vss" Then             ComboBox1.AddItem docObj.FullName       End If       Next i 

The code inside a loop such as the previous one should not change the number of objects in the collection (for example, by adding or deleting objects). Otherwise, the value of Count changes after each iteration of the loop.

To delete objects from a collection using a loop, you can decrement the counter rather than increment it. Each time an item is deleted from a collection, Count decreases by 1 and the remaining items shift position, so an incrementing loop will skip items. Use a loop such as the following:

 Dim shpsObj As Visio.Shapes Dim i As Integer 

 Set shpsObj = ActivePage.Shapes For i = shpsObj.Count To 1 Step "1       shpsObj.Item(i).Delete Next i 

Releasing an Object

An object in a program is automatically released when the program finishes running or when all object variables that refer to that object go out of scope. If an object variable is local to a procedure, it goes out of scope as soon as that procedure finishes executing. If the object variable is global, it persists until the program finishes executing, unless the object is explicitly released.

Releasing an object in a program does not affect the corresponding object in the Visio instance. For example, releasing a Document object does not close the corresponding Visio document. The document remains open, but your program no longer has access to it.

To release an object explicitly, set its object variable to the Visual Basic keyword Nothing. For example:

 Set docObj = Nothing 

If you assign the same object reference to more than one variable, be sure to set each variable to Nothing when you release the object.

Don't release an object until you're finished using it. Once you release the object, the program can no longer refer to the corresponding object in the Visio instance. For example, if you release a Document object, the program can no longer manipulate that Visio document using that variable, so it is unable to save or close the document or retrieve other objects from it.

However, if an object reference becomes invalid, you might have to release the object explicitly in your program. For example, if the user closes the Visio document or deletes a shape, references to those objects become invalid. Attempting to use any object variable that contains an invalid object reference will cause an error. To determine when to release objects from your program, you couldwrite event handlers that release objects in response to events such as BeforeShapeDelete. For details on handling events, see Chapter 21, Handling Visio Events.

Using Compound Object References

You can concatenate Visio object references, properties, and methods in single statements, as you can with Microsoft Visual Basic for Applications (VBA) objects. However, simple references are sometimes more efficient, even if they require more lines of code.

For example, the following statement refers to the first shape on the third page of the first open document in a Visio instance:

 Set shpObj = Documents(1).Pages(3).Shapes(1) 

Executing this statement retrieves one object—the Shape object assigned to shpObj. Compare the following series of statements that use simple object references:

 Set docObj = Documents.Item(1) Set pagsObj = docObj.Pages Set pagObj = pagsObj.Item(3) Set shpsObj = pagObj.Shapes Set shpObj = shpsObj.Item(1) 

Running these statements retrieves five objects: a Document object, a Pages collection, a Page object, a Shapes collection, and a Shape object. References to these objects are assigned to variables and are available for other uses, unlike the previous example. If your program will eventually need access to these intermediate objects, your code will be easier to read and maintain if you retrieve them all in this way.

Restricting the Scope and Lifetime of Object Variables

Because an object reference exists independently of the item to which it refers, object references can become invalid as a result of user actions that are beyond your program's control. For example, if you have a reference to a Shape object and the user deletes the corresponding shape, the reference still exists in your program, but it is invalid because it refers to a nonexistent shape.

You can prevent invalid references by restricting the scope and lifetime of an object variable. For example, when your program resumes execution after giving control to the user, you can release certain objects and retrieve them again to make sure the objects are still available and your program has references to the objects in their current state.

A more robust means of maintaining valid object references is to capture the events raised by the object that you are referencing. For example, if you have a reference to a Shape object, you can handle any events that might cause your variable to become invalid—for example, the BeforeShapeDelete event. For details about handling events in your program, see Chapter 21, Handling Visio Events.