Associating Data with Shapes Using Automation

3 4

You can create custom properties as well as get and set custom property values exclusively from a program, or you can collect values filled in by the user of your Microsoft Visio solution. For example, you might provide masters that prompt the user to fill in certain data when a master is dropped in a drawing, and then use a program to gather that data from the user's drawings. To establish persistent links between data in a drawing and an external data source, you can use unique I d s associated with shapes and masters.

For details about creating user-defined cells and custom properties, see Chapter 7, Enhancing Shape Behavior.

Adding Custom Property and User-defined Rows

Custom properties are a way to associate database-like fields with a shape or page, and are especially convenient if you plan to collect values entered by a user. For example, you might design a master to prompt a user to enter data when a shape is dropped on the page, and then use a Microsoft Visual Basic for Applications (VBA) program to gather the data that the user entered from the completed drawing.

The Value and Prompt cells in user-defined rows make it possible for you to store a value and reliably find it again. Because you can assign unique names to user-defined rows, it's unlikely that other programs will know about, much less attempt to write to, the cells in those rows. Scratch cells, in contrast, are likely to be used by many programs, so values you store in those cells can be overwritten when you least expect it.

You can add a custom property row or a user-defined row to a Shape object using the AddNamedRow method. If either the Custom Properties or User-Defined Cells section does not yet exist, the AddNamedRow method will add it to the ShapeSheet spreadsheet. For example, to add a user-defined row named Latitude to a shape:

 shpObj.AddNamedRow visSectionUser, "Latitude", 0 

This code is the equivalent of inserting a User-Defined Cells section in the ShapeSheet spreadsheet and replacing the default name of User_Row1 with User.Latitude. For example, to get the Value cell of the new Latitude row:

 Set celObj = shpObj.Cells("User.Latitude")  

Once you have a reference to the Cell object that is the Value cell, you can use the Formula property of that Cell object to get or set values. For example:

 celObj.Formula = "48" 

For details about the AddNamedRow method, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

Generating and Using Unique IDs

Shapes and masters can have unique IDs that you can use to distinguish shapes in a drawing or to track the original source of a master. Sophisticated database solutions typically use unique IDs to create a persistent link between a shape or master and a record in an external database. Unique IDs allow applications to bind data to shapes more reliably than is possible with shape names and IDs.

A unique ID is stored internally as a 128-bit value and is passed as a null-terminated 39-character string, formatted as in the following example:

 {2287DC42-B167-11CE-88E9-0020AFDDD917} 

Note

---

Ifa shape has a unique ID, you can assume that no other shape in the same document has the same unique ID. The Visio engine generates unique IDs using the same technology that Automation uses to guarantee unique object IDs and never reuses them.

Unique IDs for shapes

By default, shapes do not have unique IDs; a program must generate them. To generate a unique ID for a shape, use the UniqueID property of a Shape object. For example:

 IDString = shpObj.UniqueID(visGetOrMakeGUID) 

If the shape already has a unique ID, this statement gets the ID; if the shape does not have a unique ID, the statement creates one.

To find out whether a shape has a unique ID, use the following statement. If the shape has no unique ID, this statement returns a null string ( "" ).

 IDString = shpObj.UniqueID(visGetGUID) 

To delete a shape's unique ID, use the following statement:

 shpObj.UniqueID visDeleteGUID 

Some actions cause the Visio engine to delete a shape's unique ID automatically. If you cut a shape to the Clipboard and paste it once, or drag a shape to a different drawing window, its unique ID is preserved. However, if you paste the same shape from the Clipboard a second time or duplicate the shape by holding down CTRL and dragging, the new shape will not have a unique ID.

UniqueID and BaseID properties for masters

A master has both a UniqueID property and a BaseID property; both are automatically generated by the Visio engine when a new master is created.

A master's UniqueID cannot be deleted or reassigned, and changes only when you modify the master or assign a new BaseID. A master's BaseID does not change as a result of any user action, and provides a link to the original master that is more persistent than a master name or a UniqueID. You can change BaseID s using the NewBaseID property. For details, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

You can pass a unique ID as an argument to the Item method of a Shapes or Masters collection. For example:

 Set shpObj = shpsObj.Item("{2287DC42-B167-11CE-88E9-0020AFDDD917}")