Embed Size (px)
Citation preview
Public Sub Test() Dim vsoShape1 As Visio.Shape Dim vsoShape2 As Visio.Shape Dim vsoConnectorShape As Visio.Shape
Set vsoShape1 = Visio.ActivePage.Shapes(1) Set vsoShape2 = Visio.ActivePage.Shapes(2) Set vsoConnectorShape = Visio.ActivePage.Shapes.Item("Dynamic connector")
vsoShape1.AutoConnect vsoShape2, visAutoConnectDirRight, vsoConnectorShapeEnd Sub
Introduction to New Developer Features in Visio 2007
New developer-related features include data connectivity and data display, connecting shapes automatically, monitoring and filtering mouse-drag actions, and applying theme colors and theme effects. Each of these features has an associated application programming interface (API) that makes it possible to control the feature programmatically. This article provides several Microsoft Visual Basic for Applications (VBA) code samples showing how to use the new APIs.
You can control several new features in Microsoft Office Visio 2007 programmatically, including connecting to a data source, linking shapes to data, displaying linked data graphically, connecting shapes to one another automatically (AutoConnect), monitoring and filtering mouse-drag actions, and applying theme colors and theme effects.
The most important new programmable features relate to data connectivity. There are four aspects of data connectivity in Visio:
Connecting to a data source
Linking shapes to data
Displaying linked data graphically
Refreshing linked data that has changed in the data source, updating linked shapes, and resolving any conflicts
Each of these aspects has new objects and members associated with it in the Visio object model.
Connecting to Data Sources
To connect your Visio drawing to a data source programmatically, you can use the new additions to the Visio API for data connectivity, which include the following objects and their associated members:
DataRecordsets collection
DataRecordset object
DataConnection object
DataRecordsetChangedEvent object
DataColumns collection
DataColumn object
For a brief description of each object, see New Automation Objects and Members in What's New for Developers in Visio 2007 (Part 2 of 2) 1 . To see a diagram of all the members of each object, click the object names in the list.
About Data Recordsets and Data Connections
Each Visio Document object has a DataRecordsets collection, which is empty until you make a connection to a data source. To connect a Visio document to a data source, you add a DataRecordset object to the DataRecordsets collection of the document. A DataRecordset object has a DataColumns collection of DataColumn objects, each of which is mapped to a corresponding column (field) in the data source.
Data sources you can connect to include Microsoft Office Excel worksheets, Microsoft Office Access databases, Microsoft SQL Server databases, Microsoft SharePoint lists, and other OLEDB or ODBC data sources, such as an Oracle database. When you add a DataRecordset object by connecting to one of these data sources, Visio abstracts the connection in a DataConnection object, and the DataRecordset object is said to be connected.
You can also add a DataRecordset object by using an XML file that conforms to the ActiveX Data Objects (ADO) XML schema as the data source. The resulting DataRecordset object is said to be connection-less.
The connection between a data source and a DataRecordset object goes only one way—from the data source to the Visio drawing. If data in the source changes, you can refresh the data in the drawing to reflect those changes. You cannot, however, make changes in the data in the drawing and then push those changes back to the data source.
Adding DataRecordset Objects
To add a DataRecordset object to the DataRecordsets collection, you can use one of the following three methods, depending on the data source you want to connect to and whether you want to pass the method a connection string and query command string or a saved Microsoft Office Data Connection (ODC) file that contains the connection and query information:
DataRecordsets.Add
DataRecordsets.AddFromConnectionFile
DataRecordsets.AddFromXML
The following VBA sample macro shows how you might use the Add method to connect a Visio drawing to data in a Microsoft Office Excel 2007 worksheet, in this case, in the ORGDATA.XLS sample workbook that is included with Visio 2007.
VB Public Sub AddDataRecordset() Dim strConnection As String Dim strCommand As String Dim strOfficePath As String Dim vsoDataRecordset As Visio.DataRecordset strOfficePath = Visio.Application.Path strConnection = "Provider=Microsoft.ACE.OLEDB.12.0;" _ & "User ID=Admin;" _ & "Data Source=" + strOfficePath _ & "SAMPLES\1033\ORGDATA.XLS;" _ & "Mode=Read;" _ & "Extended Properties= _ & ""HDR=YES;IMEX=1;MaxScanRows=0; _ & Excel 12.0;"";" _ & "Jet OLEDB:Engine Type=35;" strCommand = "SELECT * FROM [Sheet1$]" Set vsoDataRecordset = ActiveDocument.DataRecordsets.Add(_ strConnection, strCommand, 0, "Org Data")End Sub
The Add method returns a DataRecordset object and takes four parameters:
ConnectionIDOrString The ID of an existing DataConnection object or the connection string to specify a new data-source connection. If you pass the ID of an existing DataConnection object that is currently being used by one or more other data recordsets, the data recordsets become a transacted group recordset. All data recordsets in the group are refreshed whenever a data-refresh operation occurs.
You can determine an appropriate connection string by first using the Data Selector Wizard in the Visio user interface (UI) to make the same connection, recording a macro while running the wizard, and then copying the connection string from the macro code.
CommandString The string that specifies the database table or Excel worksheet and specifies the fields (columns) within the table or worksheet that contain the data you want to query. The command string is also passed to the DataRecordset.Refresh method when the data is refreshed in the recordset.
AddOptions A combination of one or more values from the VisDataRecordsetAddOptions enumeration. These values specify certain data recordset behaviors, and make it possible, for example, to prevent the queried data in the recordset from appearing in the External Data window in the Visio UI or from being refreshed by user actions. After you assign this value, you cannot change it for the life of the DataRecordset object.
Name An optional string that gives the data recordset a display name. If you specify that data from the recordset is to be displayed in the External Data window in the Visio UI, the name you pass appears on the tab of the window that corresponds to the data recordset.
In the example, there is no existing data connection, so for the first parameter of the Add method, you pass strConnection, the connection string you defined. For the second parameter, you pass strCommand, the command string you defined, which directs Visio to select all columns from the worksheet specified. For the third parameter of the Add method, you pass zero to specify default behavior of the data recordset, and for the last parameter, you pass Org Data, the display name defined for the data recordset.
The following sample code shows how to get the DataConnection object that was created when you added a DataRecordset object to the DataRecordsets collection. It prints the connection string associated with the DataConnection object in the immediate window by accessing the ConnectionString property of the DataConnection object.
VB Public Sub GetDataConnectionObject(vsoDataRecordset As Visio.DataRecordset) Dim vsoDataConnection As DataConnection Set vsoDataConnection = vsoDataRecordset.DataConnection Debug.Print vsoDataConnection.ConnectionStringEnd Sub
Similar to how you can get the connection string associated with a DataConnection object by accessing its ConnectionString property, you can get the command string associated with a DataRecordset object by accessing its CommandString property. Both of these properties are assignable, so you can change the data source associated with a DataRecordset object or the query associated with a DataConnection object at any time, although changes are not reflected in your drawing until you refresh the data. For more information about refreshing data, see Refreshing Linked Data and Resolving Conflicts.
Accessing Data in Data Recordsets Programmatically
When you import data, Visio assigns integer row IDs, starting with the number 1, to each data row in the resulting data recordset, based on the order of the rows in the original data source. Visio uses data row IDs to track the rows when they are linked to shapes and when data is refreshed. If you want to access data rows programmatically, you must use these data row IDs. For information about how data-refresh operations affect row order, see Refreshing Linked Data and Resolving Conflicts.
You can use the DataRecordset.GetDataRowIDs method to get an array of the IDs of all the rows in a data recordset, where each row represents a single data record. The GetDataRowIDs method takes as its parameter a criteria string, which is a string that conforms to the guidelines specified in the ADO API for setting the ADO.Filter
property. By specifying appropriate criteria and using AND and OR operators to separate clauses, you can filter the information in the data recordset to return only certain data recordset rows. To apply no filter (that is, to get all the rows), pass an empty string (""). For more information about criteria strings, see Filter Property 2 in the ADO 2.8 API Reference.
After you retrieve the data-row IDs, you can use the DataRecordset.GetRowData method to get all the data stored in each column in the data row. For more information about data columns, see the section, Getting and Setting Data-Column Properties.
The following sample code shows how to use the GetDataRowIDs and GetRowData methods to return the row ID of each row and then get the data stored in each column in every row of the data recordset passed in. It uses two nested For…Next loops to iterate through all the rows in the recordset and then, for each row, iterate through all the columns in that row. The code displays the information returned in the immediate window. Note that you pass an empty string to the GetDataRowIDs method to bypass filtering and get all the rows in the recordset. After you call the procedure, note that the first set of data shown (corresponding to the first data row) contains the headings for all the data columns in the data recordset.
VB Public Sub GetDataRecords(vsoDataRecordset As Visio.DataRecordset) Dim lngRowIDs() As Long Dim lngRow As Long Dim lngColumn As Long Dim varRowData As Variant 'Get the row IDs of all the rows in the recordset. lngRowIDs = vsoDataRecordset.GetDataRowIDs("") 'Iterate through all the records in the recordset. For lngRow = LBound(lngRowIDs) To UBound(lngRowIDs) varRowData = vsoDataRecordset.GetRowData(lngRow) 'Print a separator between rows Debug.Print "------------------------------" 'Print the data stored in each column of a particular data row. For lngColumn = LBound(varRowData) To UBound(varRowData) Debug.Print "Column #"; Trim(Str(lngColumn)) & " = " & _ VarRowData(lngColumn) Next lngColumn Next lngRowEnd Sub
Linking Data to Shapes in a Visio Drawing
After you connect your Visio drawing to an external data source, you can link the shapes in the drawing to data from that source programmatically. You can link one or more shapes to a single row of data in a data recordset or to multiple rows of data in different data recordsets. However, you cannot link shapes to multiple rows of data in the same recordset.
You can link existing shapes to data, one shape at a time or as a group; or, you can create shapes and link them to data simultaneously. You can specify the correspondence between shapes and data rows, if you know it, or you can let Visio determine the correspondence automatically, based on a comparison between existing shape data and data in the data recordset.
After you link shapes to data, you can display that data graphically by adding data graphics to shapes. For more information about data graphics, see Displaying Linked Data Graphically.
The DataRecordset and DataColumn objects and the DataColumns collection expose several properties, methods, and events that facilitate data linking. In addition, several new members of existing objects in the Visio object model, including the Application, Document, Page, Selection, Shape, and Window objects, are related to data-linking.
Data-Linking and Shape Data
Linking shapes to data relies on the fact that you can assign shape data to all Visio shapes. In previous versions of Visio, shape data was called custom properties.
To access and assign shape data in the Visio UI, on the Data menu, click Shape Data. Alternatively, you can access and assign shape data manually or programmatically in the Visio ShapeSheet spreadsheet. To display the ShapeSheet spreadsheet (ShapeSheet) for a selected shape, right-click the shape and click Show ShapeSheet. To see this command, you must be running Visio in developer mode. To run Visio in developer mode, on the Tools menu, click Options, click Advanced, select Run in developer mode, and then click OK.
Within the ShapeSheet, shape data is contained in the Shape Data section (previously called the Custom Properties section). To maintain backward-compatibility, existing object members retain "custom property" or "custom properties" in their name.
If you do not assign shape data for a given shape, no Shape Data section appears in the ShapeSheet. You can add a Shape Data section to a ShapeSheet by displaying the ShapeSheet as described previously: right-click anywhere in the ShapeSheet window and click Insert Section, select Shape Data, and then click OK.
After you link shapes to data, many of the columns of the Shape Data section correspond closely to the properties of the DataColumn object. For example, the Label column in the Shape Data section, which provides the label that appears for a particular shape data item in the Shape Data dialog box, corresponds to the DataColumn.DisplayName property, which controls the name that appears for the associated data column in the External Data window.
For more information about the DataColumn object, see the section, Getting and Setting Data-Column Properties. For more information about creating shape data programmatically in the Visio ShapeSheet, see the Microsoft Office Visio 2003 SDK 3 .
Identifying Shapes, Data Recordsets, and Data Rows
Visio uses unique ID numbers to identify shapes, recordsets, and data rows. Shape IDs are unique only within the scope of the page they are on. After you determine these numbers, you can pass them to methods of the Visio data-related objects to specify exactly how the shapes in your diagram should link to data rows in the available data recordsets.
To determine the ID for a shape, get the Shape.ID property value. In addition, Visio also gives shapes unique IDs or GUIDs. The Page.ShapeIDsToUniqueIDs method takes an array of shape IDs, in addition to an enumeration value from VisUniqueIDArgs specifying whether to get, get or make, or delete shape GUIDs. The Page.ShapeIDsToUniqueIDs method also returns an array of unique IDs for the shapes passed in. Conversely, if you know the unique IDs of a set of shapes, you can use the Page.UniqueIDsToShapeIDs method to obtain the shape IDs for those shapes. For a selection of shapes, use the Selection.GetIDs method to get the shape IDs of the shapes.
To determine the ID for a DataRecordset object you add to the DataRecordsets collection, get the DataRecordset.ID property value. To determine the IDs for each of the rows in a data recordset, call the DataRecordset.GetDataRowIDs method, which returns an array of row IDs. For more information, see the section, Accessing Data in Data Recordsets Programmatically.
Creating Shapes Linked to Data
When you want to create shapes that are already linked to data, on a drawing page that either does not contain any shapes or contains shapes other than the ones you want to link, you can use the Page.DropLinked method and the Page.DropManyLinkedU method to create one or more additional shapes already linked to data. These methods resemble the existing Page.Drop and Page.DropManyU methods in that they create additional shapes at a specified location on the page; but they also create links between the new shapes and specified data rows in a specified data recordset.
The DropLinked method returns the new, linked Shape object and takes the following parameters:
ObjectToDrop The particular shape (a Rectangle shape, for example) that you want to create.
x The x-coordinate of the center of the new shape on the page.
y The y-coordinate of the center of the new shape on the page.
DataRecordsetID The value of the ID property of the DataRecordset object that contains the data row to link to.
DataRowID The value of the ID property of the data row to link to.
ApplyDataGraphicAfterLink A Boolean value specifying whether to apply the shape's data graphic automatically if it already has one, or if not, whether to apply the most recently used data graphic. The default is not to apply a data graphic. For more information about data graphics, see the section, Displaying Linked Data Graphically.
The following sample code shows how to use the DropLinked method to create a shape on the active drawing page, centered at page coordinates (2, 2), and linked to a data row. It takes the DataRecordset object passed in, gets its ID, and then passes that ID (along with the ID of the data row to link to) to the DropLinked method. The dropped shape is a simple rectangle from the Basic_U.VSS stencil, which the code opens, docked in the Visio drawing window.
In this example, the ID of the data row is set to 1; before running the code, ensure that a row with that ID exists, or change the ID value in the code.
VB Public Sub DropLinkedShape(vsoDataRecordset As Visio.DataRecordset) Dim vsoShape As Visio.Shape Dim vsoMaster As Visio.Master Dim dblX As Double Dim dblY As Double Dim lngRowID As Long Dim lngDataRecordsetID As Long lngDataRecordsetID = vsoDataRecordset.ID Set vsoMaster = _ Visio.Documents.OpenEx("Basic_U.VSS", 0).Masters("Rectangle") dblx = 2 dbly = 2 lngRowID = 1 Set vsoShape = ActivePage.DropLinked(vsoMaster, dblX, dblY, _ lngDataRecordsetID, lngRowID, True)End Sub
The DropManyLinkedU method similarly creates a set of linked shapes, returned as an array of shape IDs. It takes as parameters arrays of shapes to drop, coordinates, and data rows to link to. Entries at corresponding array-index positions determine how shapes and data rows are related and where on the page individual shapes are dropped.
Linking Existing Shapes to Data
When you know exactly how one or more existing shapes in a Visio drawing and one or more rows in a data recordset correspond to one another, you can link the existing shapes to data in the following ways:
Link a single shape to a single data row
Link a selection of shapes to one or more data rows
Link multiple shapes to multiple data rows
In addition, if you do not know the exact shape for data mapping, you can direct Visio to make the best match possible, based on limited matching information that you provide.
Linking a Single Shape to a Data Row
To link a single shape to a single data row, use the Shape.LinkToData method. This method takes a data recordset ID and data row ID and an optional Boolean flag specifying whether to display the linked data in a data graphic. The default is to display the data graphic.
Linking Multiple Shapes to Data
Two members of the Selection object, the LinkToData method and the AutomaticLink method, in addition to the Page.LinkShapesToDataRows method, make it possible to link one or more existing shapes in a selection to data.
The Selection.LinkToData method functions much like the same method of the Shape object, except that it links a selection of shapes (instead of a single shape) to a single data row.
If you are unsure about the correspondence between shapes and data rows, but you know a match exists between a specific attribute of every shape and the data in one column in the data recordset, the Selection.AutomaticLink method provides a way to link a selection of existing shapes to multiple rows of data. Note that it must be the same attribute for all shapes. For more information about this method, see the section, Linking to Data Automatically.
The Page.LinkShapesToDataRows method is similar to the Selection.LinkToData method because it links multiple shapes. However, you use this method to link shapes on the same page, rather than shapes in a selection, to data. The LinkShapesToDataRows method links shapes to multiple data rows. The LinkToData method links multiple shapes to a single row. To link shapes, pass the LinkShapesToDataRows method a pair of arrays: one for shapes, and one for data rows. Note that the matching array positions must correspond. As a result, for example, the shape at position 1 in the shape array is linked to the data at position 1 in the data row array. Again, when you call the method, you can optionally specify whether to apply an existing data graphic to linked shapes.
Linking to Data Automatically
You can use the Selection.AutomaticLink method to link shape data values in selected shapes—that is, shapes assigned to a Selection object—to data rows in a data recordset automatically—that is, without specifying the exact correspondence of all shapes and data rows. To provide Visio with enough information to create the links, however, you must supply at least one set of matching data: the name of a column in the database, a shape attribute type, and, if necessary, a shape value, all at the same index position of the corresponding arrays you pass to the method.
The shape attribute type indicates the attribute of the shape to base the matching upon. The attribute can be the value of a shape data item (formerly known as a custom property value), shape text, or another of the values specified in the VisAutoLinkFieldTypes enumeration.
For example, suppose that your drawing contains a selection of shapes representing different employees. Their shape text identifies the shapes, which in this case would be the respective employee's names. (You could use some of the employee names from the OrgData.xls workbook that is included with Visio 2007, and then connect to that data source.) To connect these shapes to a database where each employee's data constitutes a row in the database, you pass the following parameters to the AutomaticLink method:
DataRecordsetID The value of the ID property of the DataRecordset object that contains the data rows to link to. In the example that follows, you pass an existing data recordset to the procedure and get its ID.
ColumnNames() A string array consisting of names of columns in the database. At least one position in the array must have a value that corresponds to the values in the same position in the AutoLinkFieldTypes and FieldNames arrays. In the following example, you pass an array that contains the Name column name at array position 0.
AutoLinkFieldTypes() An array of Long values from the VisAutoLinkFieldTypes enumeration, consisting of shape attribute types. At least one position in the array must have a value that corresponds to the values in the same position in the ColumnNames and FieldNames arrays. In the following example, you pass the enumeration value visAutoLinkShapeText at array position 0.
FieldNames() A string array consisting of shape values. At least one position in the FieldNames array must have a value that corresponds to the values in the same position in the ColumnNames and AutoLinkFieldTypes arrays.
For most values of AutoLinkFieldTypes, for example, visAutoLinkShapeText, it is not necessary to specify the FieldNames value; you can pass the null value instead. That is the case in the following example, so you pass an empty string.
However, when you pass the visAutoLinkCustPropsLabel, visAutoLinkUserRowName, visAutoLinkPropRowNameU, or visAutoLinkUserRowNameU values of AutoLinkFieldTypes, you must pass a value for FieldNames to fully specify the shape data item to compare to the data column name.
AutoLinkBehavior A value from the VisAutoLinkBehaviors enumeration. These enumerated values provide options to customize the method, for example, to replace existing links with new ones. The following example passes the default value, 0.
ShapeIDs() An array that the method fills with the IDs of linked shapes when it returns.
The following sample shows one way to use the AutomaticLink method to link shapes and data automatically.
VB Public Sub LinkToDataAutomatically(vsoDataRecordset As Visio.DataRecordset) Dim vsoSelection As Visio.Selection Dim columnNames(1) As String Dim fieldTypes(1) As Long Dim fieldNames(1) As String Dim shapesLinked() As Long columnNames(0) = "Name" fieldTypes(0) = Visio.VisAutoLinkFieldTypes.visAutoLinkShapeText fieldNames(0) = "" ActiveWindow.DeselectAll ActiveWindow.SelectAll Set vsoSelection = ActiveWindow.Selection vsoSelection.AutomaticLink vsoDataRecordset.ID, _ columnNames, _ fieldTypes, _ fieldNames, 0, shapesLinkedEnd Sub
Discovering Links Between Shapes and Data
Use the following methods, described in Table 2 in this document, to determine which shapes are linked to data. Knowing how shapes are linked to data can help prevent conflicts and broken links:
Page.GetShapesLinkedToData
Page.GetShapesLinkedToDataRow
Shape.GetLinkedDataRow
Shape.GetCustomPropertyLinkedColumn
Shape.GetCustomPropertiesLinkedToData
Shape.IsCustomPropertyLinked
Breaking Links Between Shapes and Data
As their names imply, you can use the Shape.BreakLinkToData method and the Selection.BreakLinkToData method to break existing links between shapes and data programmatically. In addition, various changes made in the UI can break these links. For example, when users delete a data recordset, linked row, or linked shape, or when users click Unlink from Row on a shape's shortcut menu or Unlink on a row's shortcut menu, they can cause broken links.
Except when a user deletes a data recordset, row, or shape from the UI, all of these actions fire the Shape.ShapeLinkDeleted event. You can also use the methods listed in the previous section to determine link status.
Getting and Setting Data-Column Properties
Every DataRecordset object contains a DataColumns collection of all the DataColumn objects associated with the DataRecordset. These objects enable you to map data columns to cells in the Shape Data section of the ShapeSheet.
The following sample shows how to get the value of the Label cell in the Shape Data section for the first column in the data recordset passed to the method and display it in the immediate window. Then it sets the value and displays the new value.
Changing this value changes the label of the shape data item in the Shape Data dialog box for all shapes linked to rows in the data recordset. To get and set the Label cell value, you pass the visDataColumnPropertyDisplayName value from the VisDataColumnProperties enumeration to the DataColumn.GetProperty method and the DataColumn.SetProperty method.
VB Public Sub ChangeColumnProperties(vsoDataRecordset As Visio.DataRecordset) Dim strPropertyName As String Dim strNewName As String Dim vsoDataColumn As Visio.DataColumn
strNewName = "New Property Name" Set vsoDataColumn = vsoDataRecordset.DataColumns(1) strPropertyName = _ vsoDataColumn.GetProperty(visDataColumnPropertyDisplayName) Debug.Print strPropertyName vsoDataColumn.SetProperty visDataColumnPropertyDisplayName, _ strNewName strPropertyName = _ vsoDataColumn.GetProperty(visDataColumnPropertyDisplayName) Debug.Print strPropertyNameEnd Sub
Displaying Linked Data Graphically
After you link shapes in your Visio drawing to rows in a data recordset, you can graphically display the linked data programmatically. For example, suppose that your drawing contains several data-linked shapes, each of which represents a project at a particular stage of completion. You might associate a progress bar with a particular item of shape data, such as the percentage of project completion. You could then apply the progress bar to a selection of project shapes and show each project's progress toward completion visually.
Overview of Data Graphics and Graphic Items
To make it easier to display data graphically, Visio 2007 introduces the concept of data graphics and a new type of Master object called a data graphic master, which is represented in the VisMasterTypes enumeration by the value visTypeDataGraphic. To add a Master object of type visTypeDataGraphic to the Masters collection, you must use the new Masters.AddEx method.
Visio includes several types of masters, including shape masters. If you create an instance of a shape master, it becomes a shape. Visio also includes fill pattern masters, line pattern masters, and line-end masters, for which you cannot create instances. You apply these masters to shapes to impart the master pattern to the shape. Data graphic masters are more like pattern masters, because you do not create instances of them. Instead, you apply them to shapes as you do line pattern masters and fill pattern masters.
Data graphic masters correspond to the data graphics that appear in the Data Graphics task pane in the Visio UI. A data graphic master consists of one or more graphic items. Graphic items are Visio shapes designed to be ready-made
visual components that you can associate with shape data to display that data graphically, based on rules that you define, and at a position that you specify, relative to the shape.
Visio provides graphic items of the following types:
Text Displays data as text in a callout, at a specified position relative to the shape.
Color by Value Changes the color of the shape based on a comparison between shape data and a particular value or range of values.
Data Bar Uses bar charts and graphs to display data, at a specified position relative to the shape.
Icon Set Displays one of a set of icons that represents a data value or condition, at a specified position relative to the shape.
Visio provides a variety of standard data graphics that are already populated with graphic items. If you want to apply a data graphic to your shapes that has a different combination of graphic items, you can create a custom data graphic.
You should use the Visio UI to create a data graphic and add graphic items to it.
To create data graphics in the UI
1. On the Data menu, click Display Data on Shapes to open the Data Graphics task pane.
2. Click New Data Graphic and then, in the New Data Graphic dialog box, click New Item.
3. In the dialog box that opens, customize the item, and then use the same method to add custom items.
You can also create data graphic masters and populate them with existing graphic items programmatically. You cannot create graphic items programmatically, but you can customize the behavior of existing data graphics. You can also use code to change the behavior and position of graphic items, and to change the rules (called expressions) that define how individual graphic items display data.
After you create a data graphic that contains a custom combination of graphic items and define the behavior of those graphic items, you can apply the data graphic to data-linked shapes programmatically.
New Data Graphics Objects and Members
In addition to the new Master objects of type visTypeDataGraphic described in the previous section, Visio 2007 adds the following new objects and their associated members to the data graphics API:
GraphicItems collection
GraphicItem object
For a brief description of these objects, see New Automation Objects and Members in What's New for Developers in Visio 2007 (Part 2 of 2) 1 .
Visio 2007 also adds several new members of existing objects as part of the data graphics API. For example, the Shape.DataGraphic property and the Selection.DataGraphic property enable you to apply data graphics to shapes and selections respectively. The read-only Shape.IsDataGraphicCallout property indicates whether a specific shape is functioning as a data graphic item in your drawing.
Applying Data Graphics to Data-Linked Shapes
The following example shows how to use the Selection.DataGraphic property to apply an existing custom data graphic that you create in the UI to a selection of shapes in your drawing.
VB
Public Sub ApplyDataGraphic() Dim vsoSelection As Visio.Selection ActiveWindow.SelectAll Set vsoSelection = ActiveWindow.Selection Set vsoSelection.DataGraphic = _ ActiveDocument.Masters("MyCustomDataGraphic")End Sub
Customizing the Behavior of Data Graphic Masters
You can use the Master.DataGraphicHidden property and the Master.DataGraphicHidesText property to customize certain aspects of the behavior of data graphic masters.
The DataGraphicHidden property determines whether a data graphic master appears in the Data Graphics task pane in the Visio UI. If you set the value of this property to True for a given master, the master does not appear in the list of data graphics in the gallery. The default value of the property is False.
The DataGraphicsHidesText property determines whether applying a data graphic master hides the text of the shape to which it is applied (the primary shape in the case of a group shape.) The default value of this property also is False.
The GraphicItem.UseDataGraphicPosition property determines whether to use the current default callout position for graphic items of the data graphic master to whose GraphicItems collection a graphic item belongs. The default callout position for graphic items in the GraphicItems collection of a Master object of type visTypeDataGraphic is specified by the settings of the Master.DataGraphicVerticalPosition property and the Master.DataGraphicHorizontalPosition property. If UseDataGraphicPosition is True, the graphic item is positioned according to the default setting. If UseDataGraphicPosition is False, its position is determined by the settings of the GraphicItem.VerticalPosition property and the GraphicItem.HorizontalPosition property.
Also, if the HorizontalPosition and VerticalPosition property values of a graphic item are equal to the DataGraphicHorizontalPosition and DataGraphicVerticalPosition property values, the value of the UseDataGraphicPosition property for that graphic item is automatically set to True.
Note, however, that you can manually reposition a data graphic that was applied to a shape by using the control handle of the data graphic. A position set in this way takes precedence over the position specified by property settings.
The Master.DataGraphicShowBorder property determines whether a border is displayed around graphic items that are in default positions relative to the shape to which a data graphic is applied. By default, the border is hidden.
Creating Data Graphics Programmatically
The following example shows how to create a data graphic master, add an existing graphic item to it, and then modify the graphic item. This example uses the Masters.AddEx method to add a new data graphic master to the Masters collection of the current document. Next, it uses the Master.Open method to get a copy of an existing data graphic master to edit. For more information about why it is necessary to edit a copy of a master, instead of the master itself, see Open Method [Visio 2003 SDK Documentation] 4 .
Next, this example uses the GraphicItems.AddCopy method to add a copy of an existing graphic item to the GraphicItems collection of the new master, and the GraphicItem.SetExpression method to modify the data field that the graphic item represents. It also sets the GraphicItem.PositionHorizontal property to modify the horizontal position of the graphic item relative to the shape to which it is applied.
Finally, it sets the Master.DataGraphicHidesText property to True to hide the text of the shape, and closes the copy of the master, which applies the changes to existing shapes to which this data graphic master is applied. You can then apply the new data graphic master to additional shapes.
VB Public Sub AddNewDataGraphicMaster() Dim vsoMaster As Visio.Master
Dim vsoMasterCopy As Visio.Master Dim vsoMaster_Old As Visio.Master Dim vsoGraphicItem As GraphicItem Dim vsoGraphicItem_Old As Visio.GraphicItem Set vsoMaster = ActiveDocument.Masters.AddEx(visTypeDataGraphic) Set vsoMasterCopy = vsoMaster.Open Set vsoMaster_Old = ActiveDocument.Masters("old_master_name") Set vsoGraphicItem_Old = vsoMaster_Old.GraphicItems(1) Set vsoGraphicItem = _ vsoMasterCopy.GraphicItems.AddCopy(vsoGraphicItem_Old) vsoGraphicItem.SetExpression visGraphicExpression, _ "new_data_field_name" vsoGraphicItem.PositionHorizontal = visGraphicLeft vsoMasterCopy.DataGraphicHidesText = True; vsoMasterCopy.CloseEnd Sub
The preceding code assumes that you know the name of the existing data graphic master that contains one or more graphic items you want to add to the new master, and that you know the IDs of one or more graphic items you want to add to the master. You can determine the name of an existing data graphic master by moving your mouse over the master in the Data Graphics task pane. You can also determine master names and IDs by iterating through the Masters collection in the current document, as shown in this code example.
VB For intCounter = 1 To ActiveDocument.Masters.Count If ActiveDocument.Masters(intCounter).Type = _ visTypeDataGraphic Then Debug.Print ActiveDocument.Masters(intCounter).Name, _ ActiveDocument.Masters(intCounter).ID End If Next
Similarly, you can iterate through the GraphicItems collection of a master to determine the values of the ID property and the Tag property of an existing graphic item, as shown in the following example. The Tag property is a string that Visio does not use. It is empty by default. However, you can set its value to make it easier to identify individual graphic items programmatically.
VB For intCounter = 1 To (vsoMaster_Old.GraphicItems.Count) Debug.Print vsoMaster_Old.GraphicItems(intCounter).ID, _ oldMaster.GraphicItems(intCounter).Tag Next
To see a code sample that shows how to customize data graphics programmatically, download the Visio 2007: Software Development Kit 5 and see the Code Samples Library.
Refreshing Linked Data and Resolving Conflicts
When data changes in the data source to which your drawing is connected, you can refresh the data in your Visio drawing to reflect those changes. You can specify that Visio refresh data automatically at a specified interval by setting the DataRecordset.RefreshInterval property. You can refresh data programmatically by calling the DataRecordset.Refresh method.
You can also resolve any conflicts in the relationship between shapes and rows of data. Conflicts can occur if you refresh the data recordset and some data rows to which shapes were linked before the refresh operation no longer exist, because of changes to the data source. Other conflicts are possible when two or more rows in the refreshed recordset have identical primary keys.
Refreshing Linked Data Automatically
When you create a DataRecordset object, its RefreshInterval property is set to the default, 0. This setting indicates that data is not refreshed automatically. By setting DataRecordset.RefreshInterval to a positive Long value, you can specify the time in minutes between automatic refreshes. The minimum interval you can specify is one minute. This setting corresponds to the value a user can set in the Configure Refresh dialog box.
To determine the date and time of the last refresh operation, get the DataRecordset.TimeRefreshed property.
Additionally, the DataRecordset.RefreshSettings property enables you to customize automatic refreshes of data. By setting this property to a combination of the values in the VisRefreshSettings enumeration, you can specify that either or both of the following occur:
The UI for reconciling refresh conflicts (the Refresh Conflicts task pane) is disabled. (See the next section for more information.)
Refresh operations automatically overwrite changes to data made in the UI.
The default value for this property is 0, meaning that neither of these events occur.
Identifying Data Recordset Rows for Refresh Operations
Because shapes are linked by their shape IDs to specific data rows, when Visio refreshes linked data, it must determine which rows in the linked data recordset or recordsets were added, changed, or removed since the last time the data was refreshed.
To identify these rows, Visio uses the row IDs assigned to the rows in the data recordset. Visio can assign these row IDs two ways, depending on whether you designated primary keys for the data recordset when you created it.
Refreshing Data Recordsets That Do Not Have Primary Keys
When you create a data recordset, Visio assigns row IDs to all the rows in the recordset based on the existing order of the rows in the data source. Accordingly, the first row in the recordset is always assigned row ID 1, the second is assigned row ID 2, and so on.
Subsequently, data rows can be added or removed from the original data source. Then, when data is refreshed, the data recordset reflects those changes. As a result, row order in the data recordset may change.
For example, in a five-row data recordset, if the fourth row in the data source is removed, when Visio refreshes the data recordset connected to that data source, the fifth row in the data recordset becomes the new fourth row and is assigned row ID 4. Row ID 5 is removed from the data recordset. As a result, shapes linked to row ID 5 lose their links, and shapes linked to row ID 4 now get data from the row previously in the fifth position.
As you can see, not assigning primary keys to data recordsets when you create them can result in broken links between shapes and data, or in Visio linking shapes to rows other than the ones to which you want them linked.
Refreshing Data Recordsets That Have Primary Keys
You can help prevent these broken or mismatched links by assigning primary keys to data recordsets. A primary key identifies the name of the data column or columns that contain unique identifiers for each row. The value in the primary key column for each row uniquely identifies that row in the data recordset. Primary keys are often ID values, but you can set any column or combination of columns to be the primary key. However, to get consistent results when you refresh data, it is essential that you make the primary key column value (or set of values for multiple primary key columns) unique for each row.
As a result, when you refresh or when Visio refreshes a data recordset that includes primary keys, its rows retain the same row IDs they had before the refresh operation. Because Visio links shapes to data rows by ID—shape ID to row ID—and because row IDs remain the same after a refresh operation, data-linked shapes remain linked to the correct row. Note that row IDs are never recycled for a given a data recordset.
You can use the DataRecordset.GetPrimaryKey method to determine the existing primary key for a data recordset, if one is specified. This method returns the primary key setting for the data recordset, as a value from the VisPrimaryKeySettings enumeration. You can use single primary keys or composite primary keys. A single key bases row identification on the values in a single column. A composite primary key uses two or more columns to identify a row uniquely.
If the primary key setting is visKeySingle or visKeyComposite, the method also returns an array of primary key column-name strings. If the primary key setting is visKeyRowOrder (the default) the method returns an empty array of primary keys.
Similarly, you can use the DataRecordset.SetPrimaryKey method to specify the primary key setting for the data recordset, and the name of the column or columns that you want to set as the primary key column or columns. Remember, when you set primary keys, ensure that the column or columns you choose to be primary key columns contain unique values (or value sets) for each row.
Refreshing Linked Data Programmatically
To refresh a connected data recordset programmatically, call the DataRecordset.Refresh method. Calling this method executes the query string associated with the data recordset and then updates the linked shapes with the data returned by the query.
Calling the Refresh method on a particular DataRecordset object results in refreshing all other DataRecordset objects associated with the same DataConnection object (that is, those objects that have the same value for their DataConnection property). DataRecordset objects sharing the same DataConnection property value are called transacted data recordsets.
If calling Refresh results in conflicts, Visio displays the Refresh Conflicts task pane in the UI, unless you set the RefreshSettings property to include the visRefreshNoReconciliationUI enumerated value.
Before you refresh linked data, if you want to change the query Visio uses to retrieve the data to query a different table in the same database, set the DataRecordset.CommandString property to a new value. To connect to an entirely new data source, set both the DataRecordset.CommandString property value and the DataConnection.ConnectionString property value.
The DataRecordset.GetLastDataError method gets the ADO error code, ADO description, and data recordset ID associated with the most recent error that resulted from adding a new data recordset or from refreshing the data in an existing data recordset.
Identifying and Resolving Conflicts
When you or Visio refresh data and a resulting conflict occurs, you can use the DataRecordset.GetAllRefreshConflicts method and the DataRecordset.GetMatchingRowsForRefreshConflict method to determine why the conflict arose. The GetAllRefreshConflicts method returns an array of shapes for which a conflict exists between data in the shape and data in the data-recordset row to which the shape is linked. To determine which data-recordset rows produced the conflict, you can then pass each of these shapes to the GetMatchingRowsForRefreshConflict method, which returns an array of rows that are in conflict.
Rows in the data recordset can conflict when two or more of them have identical primary keys, and may link to the same shape. When this occurs, GetMatchingRowsForRefreshConflict returns an array containing at least two row IDs.
Conflicts can also occur when a previously data-linked row from the data recordset is removed. When this occurs, the method returns an empty array.
To remove the conflict, pass the shape to the DataRecordset.RemoveRefreshConflict method, which removes the conflicting information from the current document.
Other Additions to the Visio Object Model
In addition to the new objects and members related to data connectivity, the Visio object model now includes several other new members that make it easier to apply theme effects and theme colors, to draw connections between shapes on the drawing page, and to accomplish several other tasks.
Applying Theme Colors and Theme Effects
You can get and set the theme colors and theme effects applied to the active document or page in your Visio drawing programmatically by using two new properties of the Page object, the Page.ThemeColors property and the Page.ThemeEffects property. You can apply any of the built-in Visio theme colors and theme effects. You can view them in the Theme – Colors task pane and the Theme - Effects task pane in the Visio UI. By moving your mouse over one of the themes in the task panes, you can determine the property value to assign to apply that theme.
You can also get these names programmatically by using the Document.GetThemeNames method and the Document.GetThemeNamesU method. These methods take as a parameter either the visTypeThemeColors enumerated value or the visTypeThemeEffects enumerated value from the VisThemeTypes enumeration. They return an array of theme names.
You can set theme colors and theme effects for a page by setting the Page.ThemeColors property value and the Page.ThemeEffects property value to one of the following:
A numeric value from the VisThemeColors enumeration or from the VisThemeEffects enumeration, for colors and effects, respectively
A string value equal to the theme name
A reference to a master, as explained in the next paragraph
Theme colors are actually masters of type visTypeThemeColorsMaster. Theme effects are masters of type visTypeThemeEffectsMaster. Theme colors masters and theme effects masters are like data graphic masters in that you ordinarily do not create instances of them.
Alternatively, you can create your own theme colors or theme effects and apply them by using the same properties. For sample code that shows how to create themes, see the sample "Customizing Themes" in the Code Samples Library in the Visio 2007 SDK.
Drawing Shape Connectors Programmatically
You can automatically draw connections between shapes on the drawing page while specifying the direction of the connection and, optionally, the connector. The following code example shows how to use the Shape.AutoConnect method to draw a connection between two flowchart shapes, a Decision shape and a Process shape, by using a third (Dynamic Connector) shape, all of which were added to an empty drawing page from the Basic Flowchart Shapes stencil.
Because the example calls the method on the Decision shape, Visio draws the connector from the Decision shape to the Process shape. Because we pass the method the enumerated value visAutoConnectDirRight (from the VisAutoConnectDir enumeration) as the required second parameter, Visio places the Process shape automatically to the right of the Decision shape on the drawing page, regardless of its previous location.
VB Public Sub AutoConnectShapes() Dim vsoShape1 As Visio.Shape Dim vsoShape2 As Visio.Shape Dim vsoConnectorShape As Visio.Shape
Set vsoShape1 = Visio.ActivePage.Shapes("Decision") Set vsoShape2 = Visio.ActivePage.Shapes("Process") Set vsoConnectorShape = Visio.ActivePage.Shapes("Dynamic _ connector") vsoShape1.AutoConnect vsoShape2, visAutoConnectDirRight, _
vsoConnectorShapeEnd Sub
Other New Features of the Visio Object Model
Visio 2007 adds several other new members to the object model in the following categories:
Removing hidden information.
New document check-out and check-in methods.
New language settings properties.
New extensions to the MouseMove event. Visio 2007 also provides you the ability to filter the extensions to listen to only the ones you specify.
Miscellaneous application settings.
New Automation Objects and Members
Visio 2007 adds new objects to the object model. See Table 1.
Table 1. New objects in Visio 2007
Object Description
DataColumn Enables custom mapping of a database column to a ShapeSheet cell.DataColumns The collection of DataColumn objects associated with a DataRecordset object.
DataConnectionAbstracts communication between one or more DataRecordset objects and a database.
DataRecordsetA container for data queried from a data source. Stores, formats, refreshes, and exposes data queried from a database in Visio.
DataRecordsetChangedEvent Returned as an argument when data-related events fire.DataRecordsets The collection of DataRecordset objects associated with a Document object.GraphicItem A single part of a data graphic master (a master of type visTypeDataGraphic).
GraphicItemsThe collection of GraphicItem objects associated with a master of type visTypeDataGraphic.
Visio 2007 adds new methods to the object model. See Table 2.
Table 2. New methods in Visio 2007
Method Objects Description
AddCopy GraphicItemsAdds a copy of a GraphicItem object to the GraphicItems collection.
AddEx MastersAdds a master of the specified VisMasterTypes object to the Masters collection.
AddFromConnectionFile DataRecordsets
Adds a DataRecordset object to the DataRecordsets collection, associates it with a new or existing DataConnection object, and fills it with data from an OLEDB or ODBC data source by using the connection and query information stored in a specified ODC connection file.
AddFromXML DataRecordsetsAdds a DataRecordset object to the DataRecordsets collection and fills it with data from an XML file, without requiring a DataConnection object.
AutoConnect ShapeConnects one shape to another shape in the direction specified.
AutomaticLink Selection
Automatically matches shapes to data rows by comparing shape-attribute values with recordset-data-row values and finding the best match. You can specify the column (field) in each row of data and the shape attribute upon which to base the comparison.
BreakLinkToDataSelection, Shape
Breaks the link between one or more shapes and the data row or rows to which the shape or shapes are linked.
CanUndoCheckOut DocumentDetermines whether a document is checked out so that the checkout can be subsequently undone.
DataGraphicDelete MasterDeletes the Master object of type visTypeDataGraphic from the Masters collection of the document.
DropLinked Page Creates a shape linked to data on the page.DropManyLinkedU Page Creates many shapes linked to data on the same page.
ExportAsFixedFormat DocumentExports a Visio document as a file in a fixed format, either PDF or XPS.
GetAllRefreshConflicts DataRecordsetReturns an array of all the shapes in the data recordset that have refresh conflicts.
GetCustomPropertiesLinkedToData ShapeReturns an array of indices of shape data linked to a particular data recordset.
GetCustomPropertyLinkedColumn ShapeReturns the name of the column in the specified data recordset that is linked to the specified shape-data (custom property) field.
GetDataRowIDs DataRecordsetReturns an array of data recordset row IDs that match the rows in the data recordset specified in the criteria string passed to the method.
GetExpression GraphicItemReturns the current expression for the primary key column corresponding to the specified field.
GetFilterActions EventReturns an array of the filter actions set for the Event object.
GetIDs SelectionReturns an array of the IDs of shapes in a selection so that you can link them to data.
GetLastDataError DataRecordsets
Gets the ActiveX Data Objects (ADO) error code, ADO description, and data recordset ID associated with an error that results from adding a new data recordset or refreshing the data in an existing recordset.
GetLinkedDataRecordsetIDs ShapeReturns an array of the IDs of data recordsets linked to a shape.
GetLinkedDataRow ShapeReturns the ID of the row to which a shape is linked in the specified data recordset.
GetMatchingRowsForRefreshConflict DataRecordsetReturns an array of IDs of data rows that may have a broken link to a specified shape after a refresh operation.
GetPrimaryKey DataRecordsetReturns the name of the primary key column of the data recordset.
GetProperty DataColumnReturns the value of the data column property passed in as VisDataColumnProperties.
GetRowData DataRecordsetReturns an array of values for each column in the specified data row. Returns an array of column names when data row 0 is specified.
GetShapesLinkedToData PageReturns an array of shapes on the page linked to a specific data recordset.
GetShapesLinkedToDataRow PageReturns an array of shapes on the page linked to a particular data row in a data recordset.
GetThemeNames DocumentReturns an array of strings that represent the locale-specific names of all the theme colors or theme effects associated with the document.
GetThemeNamesU Document Returns an array of strings that represent the locale-independent names of all the theme colors or theme effects
associated with the document.
IsCustomPropertyLinked ShapeDetermines whether a specified shape data item (a custom property) is linked to a particular data recordset.
LinkShapesToDataRows Page
Links an array of shapes to an array of data rows from a particular data recordset on a one-to-one basis, by matching positions in the arrays. Optionally, applies a data graphic to linked shapes.
LinkToDataSelection, Shape
Links a single data-recordset row to a shape or to all shapes in a selection. Optionally, applies a data graphic to linked shapes.
Refresh DataRecordset Refreshes the data in the data recordset.
RefreshUsingXML DataRecordsetRefreshes the data in a data recordset that has no data connection.
RemoveHiddenInformation DocumentRemoves the specified VisRemoveHiddenInfoItems items from the document.
RemoveRefreshConflict DataRecordset Removes all conflict information from the drawing file.
SetColumnProperties DataColumnsSets the properties of the specified columns to the values specified.
SetExpression GraphicItemSets the value of the expression string that is part of a GraphicItem object's rule, against which shape data is evaluated.
SetFilterActions EventSpecifies which extensions to the MouseMove event Visio will report.
SetPrimaryKey DataRecordsetSets the column name of the primary key column used during a refresh operation.
SetProperty DataColumnSets the specified property (as VisDataColumnProperties) to the specified value.
ShapeIDsToUniqueIDs PageReturns an array of unique IDs (GUIDS) for shapes specified by their shape IDs.
UndoCheckOut DocumentCloses and reopens a checked-out document; deletes the private copy of the document, discarding any changes; and undoes the checkout
UniqueIDsToShapeIDs PageReturns an array of shape IDs for shapes specified by their unique IDs (GUIDS).
Visio 2007 adds new properties to the object model. See Table 3.
Table 3. New properties in Visio 2007
Property Objects Description
ApplyThemesOnShapeAdd ApplicationSettingsGets or sets the current setting for whether to apply themes on shape drop or paste.
Assistance Application, InvisibleApp
Gets a reference to the Microsoft Office (MSO) IAssistance object, which provides a way for developers to create a customized help experience for users within Microsoft Office. Read-only.
BIDITextUI ApplicationSettings
Gets the current setting for display of right-to-left languages. Corresponds to the regional options setting in the Microsoft Office Language Settings 2007 dialog box. Read-only.
CommandString DataRecordsetGets or sets the command string used to query the data source.
ConnectionString DataConnectionGets or sets the connection string used to access an existing DataConnection object or to create a new DataConnection object.
ContainsWorkspaceEx DocumentGets or sets the current setting for whether workspace information is saved with the document.
DataAsXML DataRecordset
Permits exporting data in XML format from Visio. Gets the XML string describing the data recordset following the ADO XML schema. Contains all the rows in the data recordset with Visio row IDs pre-pended to them. Read-only.
DataColumns DataRecordsetReturns the DataColumns object associated with the DataRecordset object.
DataColumnsAdded DataRecordsetChangedEventReturns an array of the IDs of columns added to the data recordset as part of a refresh operation. Read-only.
DataColumnsChanged DataRecordsetChangedEventReturns an array of the IDs of columns in the data recordset whose type changed as part of a refresh operation. Read-only.
DataColumnsDeleted DataRecordsetChangedEventReturns an array of the IDs of columns deleted from the data recordset as part of a refresh operation. Read-only.
DataConnection DataRecordset
Returns the DataConnection object associated with the DataRecordset object. Returns Nothing for a connectionless DataRecordset object. Read-only.
DataFeaturesEnabled Application, InvisibleAppTrue if data features are enabled for the current instance of Visio. Read-only.
DataGraphicGraphicItems, GraphicItem, Selection, Shape
Returns the Master object of type visTypeDataGraphic that is the parent of the GraphicItem object, the GraphicItems collection, the Selection object, or the Shape object.
DataGraphicHidden MasterDetermines whether the data graphic is visible in the Data Graphics task pane.
DataGraphicHidesText MasterIf set to True, hides the text of the primary shape when a data graphic master is applied. The default is False.
DataGraphicHorizontalPosition Master
Gets or sets the horizontal position of a data graphic relative to the shape it is applied to, based on the specified VisGraphicPositionHorizontal value.
DataGraphicShowBorder Master
Gets or sets whether a border appears around GraphicItem objects whose UseDataGraphicPosition property is set to True, or that occupy the same position as the data graphic of which they are a part.
DataGraphicVerticalPosition Master
Gets or sets the vertical position of a data graphic relative to the shape it is applied to, based on the specified VisGraphicPositionVertical value.
DataRecordsetDataColumns, DataColumn, DataRecordsetChangedEvent
Returns the DataRecordset object associated with the parent object.
DataRecordsets DocumentReturns the collection of DataRecordset objects associated with the Document object.
DataRowsAdded DataRecordsetChangedEventReturns an array of the IDs of rows added to the data recordset as part of a refresh operation. Read-only.
DataRowsDeleted DataRecordsetChangedEvent Returns an array of the IDs of rows in the data recordset whose type content was changed or deleted as part of a refresh operation. Read-
only.
DefaultRectangleDataObject Application, InvisibleApp
Returns an IDataObject interface that represents the Rectangle tool used in the Visio UI. Produces results similar to those you get by dragging a data recordset row onto the page. Useful when no master is selected in a docked stencil. Read-only.
DefaultSavePath DocumentGets or sets the path to the location where Visio saves documents by default.
DisplayName DataColumn
Gets or sets the display name for the data column in the External Data window and the label for the associated text box in the Shape Data dialog box for the linked shape or shapes.
EnableAutoConnect ApplicationSettings
Permits the user to disable the AutoConnect functionality, which is on by default. Corresponds to the EnableAutoConnect setting in the Options dialog box.
GraphicItems MasterReturns the GraphicItems collection of the Master object. Read-only
HorizontalPosition GraphicItemGets or sets the horizontal position of a graphic item relative to a container or shape, as VisGraphicPositionHorizontal.
KashidaTextUI ApplicationSettings
Gets the current setting for display of Kashida text-justification in certain cursive languages. Corresponds to the regional options setting in the Microsoft Office Language Settings 2007 dialog box. Read-only.
LanguageSettings Application, InvisibleAppReturns a reference to the Microsoft Office LanguageSettings interface. Read-only.
LinkReplaceBehavior DataRecordsetGets or sets how existing links between shapes and data rows are handled during application of the Selection.AutomaticLink method.
MyShapesPath Application, InvisibleApp Gets or sets the path to the My Shapes folder.
PositionRelativeTo GraphicItem
Gets or sets whether the graphic item is positioned relative to a container or to a primary shape, as VisGraphicPositionRelativeTo.
RefreshInterval DataRecordset
Gets or sets the refresh interval for the data recordset in minutes. Default value is 0, which means that refreshing by interval never occurs. Minimum value is one minute.
RefreshSettings DataRecordsetGets or sets refresh settings for the data recordset, as a combination of VisRefreshSettings values.
SATextUI ApplicationSettings
Gets the current setting for display of South Asian languages. Corresponds to the regional options setting in the Microsoft Office Language Settings 2007 dialog box. Read-only.
SelectedDataRecordset WindowGets or sets the DataRecordset object that is selected on the active tab of the External Data window.
SelectedDataRowID WindowGets or sets the row ID of the selected row displayed on the active tab of the External Data window.
ShowMoreShapeHandlesOnHover ApplicationSettingsGets or sets whether to show additional shape handles when the mouse is paused over a shape.
ShowShapeSearchPane ApplicationSettings Gets or sets whether the Shape Search pane is
visible in the UI.
Tag GraphicItem
Gets or sets an expression that stores extra data needed for your program. For example, the name you want to apply to a graphic item. Not used by Visio.
ThemeColors Page
Gets or sets the current theme color applied to the page. Can be a string, a Master object of type visTypeThemeColorsMaster, or an enumeration value from VisBuiltInThemeColors.
ThemeEffects Page
Gets or sets the theme effect currently applied to the page. Can be a string, a Master object of type visTypeThemeEffectsMaster, or an enumeration value from VisBuiltInThemeEffects.
Timeout DataConnection
Gets or sets how long (in seconds) to attempt to establish a data connection before terminating the attempt and generating an error. Default is 15 seconds.
TimeRefreshed DataRecordsetReturns the date and time of the last refresh operation. Read-only.
UseDataGraphicPosition GraphicItem
Gets or sets whether a GraphicItem object inherits the DataGraphicHorizontalPosition property setting and DataGraphicVerticalPosition property setting of the data graphic master to which it belongs (when set to True), or whether to apply the GraphicItem object's own HorizontalPosition setting and Vertical Position setting (when set to False).
VerticalPosition GraphicItemGets or sets the vertical position of the graphic item relative to a container or shape, as VisGraphicPositionVertical.
Visio 2007 adds new events to the object model. See Table 4.
Table 4. New events in Visio 2007
Event Objects Description
AfterRemoveHiddenInformationApplication, Document, Documents, DrawingControl, InvisibleApp
Occurs when hidden information is removed from the document.
AfterResumeEvents Application, InvisibleApp Occurs after firing of events is resumed.
BeforeDataRecordsetDeleteApplication, DataRecordset, DataRecordsets, Document, Documents, InvisibleApp
Fired before a DataRecordset object is deleted.
BeforeSuspendEvents Application, InvisibleApp Occurs before firing of events is suspended.
DataRecordsetAddedApplication, DataRecordsets, Document, Documents, InvisibleApp
Fired after a DataRecordset object is added.
DataRecordsetChangedApplication, DataRecordsets, Document, Documents, InvisibleApp
Fired after a DataRecordset object is refreshed. Examine the associated DataRecordsetChangedEvent object to determine if changes occurred.
GroupCanceled
Application, Document, Documents, InvisibleApp, Master, Masters, Page, Pages, Shape
Fired when a shape-grouping operation is canceled.
QueryCancelGroup
Application, Document, Documents, InvisibleApp, Master, Masters, Page, Pages, Shape
Fired after a user requests to cancel a shape-grouping operation.
QueryCancelSuspendEvents Application, InvisibleAppOccurs before the application suspends events in response to client code. If any event handler returns True, the operation is canceled.
ShapeDataGraphicChanged
Application, Document, Documents, InvisibleApp, Master, Masters, Page, Pages, Shape
Fired after the data graphic assigned to a shape changes.
ShapeLinkAddedApplication, Document, InvisibleApp, Page, Pages, Shape
Fired after a Shape object is linked to data.
ShapeLinkDeletedApplication, Document, InvisibleApp, Page, Pages, Shape
Fired when the link between a Shape object and data is broken.
SuspendEventsCanceled Application, InvisibleAppOccurs after an event handler has returned True (cancel) to a QueryCancelSuspendEvents event.
Visio 2007 adds new enumerations to the object model. See Table 5.
Table 5. New enumerations in Visio 2007
Enumeration Description
VisAutoConnectDir Shape placement directions passed to the Shape.AutoConnect method.
VisAutoLinkBehaviorsAutomatic data-linking behavior options passed to the Selection.AutomaticLink method.
VisAutoLinkFieldTypesField types used with automatic data-linking passed to the Selection.AutomaticLink method.
VisDataColumnPropertiesData-column properties for a shape linked to data passed to the DataColumn.SetProperty method and returned by the DataColumn.GetProperty method.
VisDataRecordsetAddOptions Options for adding a data recordset, passed to the DataRecordsets.Add method.VisDocExIntent Export intent constants passed to the Document.ExportAsFixedFormat method.
VisFilterActionsDrag-state extensions of the MouseMove event to filter; passed to the Event.SetFilterActions method and returned by the Event.GetFilterActions method.
VisFixedFormatTypes File format types passed to the Document.ExportAsFixedFormat method.
VisGraphicFieldGraphic item field types returned by the GraphicItem.GetExpression method, and passed to the GraphicItem.SetExpression method.
VisGraphicItemTypes Graphic item types returned by the GraphicItem.Type property.
VisGraphicPositionHorizontalHorizontal data-graphic position options passed to and returned by the GraphicItem.PositionHorizontal property.
VisGraphicPositionVerticalVertical data-graphic position options passed to and returned by the GraphicItem.PositionVertical property.
VisLinkReplaceBehaviorOptions for replacing existing links between shapes and data rows during automatic linking; passed to and returned by the DataRecordset.LinkReplaceBehavior property.
VisMasterTypes Master types returned by the Master.Type property.VisMouseMoveDragStates Mouse drag-state constants returned by the MouseEvent.DragState property.
VisPrimaryKeySettingsPrimary-key settings for a data recordset, passed to the DataRecordset.SetPrimaryKey method and returned by the DataRecordset.GetPrimaryKey method.
VisRefreshSettingsData-refresh settings passes to the DataRecordsets.Add method and returned by the DataRecordset.RefreshSettings property.
VisRemoveHiddenInfoItems Types of items that you can remove by using the
Document.RemoveHiddenInformation method.VisThemeColors Theme color constants passed to and returned by the Page.ThemeColors property.VisThemeEffects Theme effect constants passed to and returned by the Page.ThemeEffects property.
VisThemeTypesTheme type constants passed to the Document.GetThemeNames method and the Document.GetThemeNamesU method.
New ShapeSheet Cells and Functions
Note:
The Custom Properties section of the ShapeSheet is now called the Shape Data section.
Visio 2007 adds new ShapeSheet functions to the list of functions. See Table 6.
Table 6. New ShapeSheet functions in Visio 2007
Function Description
ARG(ArgName,[DefaultValue])
Takes a string that contains the name of an argument that the calling cell can pass to the function, and contains the default value returned by the function if the calling cell does not pass in a value for the ArgName parameter (optional). Returns the value specified by the calling cell and the matching ArgName parameter.
BLEND(Color1,Color2,Float[0,1])Blends two colors (as Visio color index or RGB value) based on the value specified in the Float parameter, which is a real number between 0 and 1, inclusive.
CELLISTHEMED()Enables you to apply a theme to a shape and to format the shape manually.
EVALCELL(CellRef,[Arg1Name,Arg1],[Arg2Name,Arg2],…)
Takes a reference to a cell that contains a custom function and one or more name-value pairs to pass to the custom function as arguments (optional). Returns the calculated result of the custom function given the specified arguments and values.
HUEDIFF(Color1,Color2)Returns the difference in hue between Color1 and Color2.
LUMDIFF(Color1,Color2)Returns the difference in luminosity between Color1 and Color2.
SATDIFF(Color1,Color2)Returns the difference in saturation between Color1 and Color2.
SHADE(Color,Int)Modifies the color (as Visio color index or RGB value) by decreasing its luminosity by the amount specified in the Int parameter.
THEME() Gets the current theme's format settings.
THEMEGUARD()Guards the formatting cells of a shape to ensure that they use appropriate aspects of the current theme.
THEMERESTORE()
Stores the local formatting value of a shape when you apply a theme so that you can restore the local formatting if the user subsequently removes the theme.
TINT(Color,Int)Modifies the color (as Visio color index or RGB value) by increasing its luminosity by the amount specified in the Int parameter.
TONE(Color,Int)Modifies the color (as Visio color index or RGB value) by decreasing its saturation by the amount specified in the Int parameter.
Visio 2007 adds new ShapeSheet cells. See Table 7.
Table 7. New ShapeSheet cells in Visio 2007
Cell Section Description
EventMultiDrop EventsAn event cell that is evaluated when multiple shapes are dropped on the drawing page, either as instances or when shapes are duplicated or pasted.
LockFromGroupFormat Protection
Blocks format changes to a group shape from being propagated to its subshapes, while still allowing user formatting of a selected subshape. Corresponds to the From group formatting check bock in the Protection dialog box.
LockThemeColors ProtectionPrevents application of theme colors to the shape. Corresponds to the From theme colors check box setting in the Protection dialog box.
LockThemeEffects ProtectionPrevents application of theme effects to the shape. Corresponds to the From theme effects check box setting in the Protection dialog box.
RTLText Character Determines whether the character run is left-to-right or right-to-left.ShapePlaceStyle ShapeLayout Stores layout style and alignment values from VisCellIndices.UseVertical Character Determines whether the character run is vertical or horizontal.
Deprecated and Changed Object Model Members
The following items are deprecated in Visio 2007:
The ApplicationSettings.ShowStartupDialog property
The Document.ContainsWorkspace property
The visEventLayer member of VisEventCodes
The visCmdNMMeetNow member of VisUICmds
Also note that the visCalThaiBuddhism member of VisCellVals is changed to visCalThaiBuddhist (= 5).
