What's New for Developers in Visio 2007 (Part 2 of 2)

Article
05/23/2014

Saul Candib, Microsoft Corporation

Philippe-Joseph Arida, Microsoft Corporation

August 2006

Applies to: 2007 Microsoft Office Suites, Microsoft Office Visio 2007

Summary: This article describes all new objects and members of the Visio 2007 VBA object model and newly deprecated existing members. (18 printed pages)

Contents

Introduction to What's New for Developers in Visio 2007 (Part 2 of 2)
New Automation Objects and Members
New ShapeSheet Cells and Functions
Deprecated and Changed Object Model Members
Conclusion
Additional Resources

Introduction to What's New for Developers in Visio 2007 (Part 2 of 2)

This is the second part of a two-part article describing new features of interest to developers in Microsoft Office Visio 2007 and explaining their purposes and functions.

What's New for Developers in Visio 2007 (Part 1 of 2) introduces the new features of interest to developers in Visio 2007 and explains how to use them.
What's New for Developers in Visio 2007 (Part 2 of 2) describes all new objects and members of the Visio Microsoft Visual Basic for Applications (VBA) object model and newly deprecated existing members. It also lists and describes new ShapeSheet cells and functions.

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.
DataConnection	Abstracts communication between one or more DataRecordset objects and a database.
DataRecordset	A 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).
GraphicItems	The 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	GraphicItems	Adds a copy of a GraphicItem object to the GraphicItems collection.
AddEx	Masters	Adds 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	DataRecordsets	Adds a DataRecordset object to the DataRecordsets collection and fills it with data from an XML file, without requiring a DataConnection object.
AutoConnect	Shape	Connects 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.
BreakLinkToData	Selection, Shape	Breaks the link between one or more shapes and the data row or rows to which the shape or shapes are linked.
CanUndoCheckOut	Document	Determines whether a document is checked out so that the checkout can be subsequently undone.
DataGraphicDelete	Master	Deletes 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	Document	Exports a Visio document as a file in a fixed format, either PDF or XPS.
GetAllRefreshConflicts	DataRecordset	Returns an array of all the shapes in the data recordset that have refresh conflicts.
GetCustomPropertiesLinkedToData	Shape	Returns an array of indices of shape data linked to a particular data recordset.
GetCustomPropertyLinkedColumn	Shape	Returns the name of the column in the specified data recordset that is linked to the specified shape-data (custom property) field.
GetDataRowIDs	DataRecordset	Returns 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	GraphicItem	Returns the current expression for the primary key column corresponding to the specified field.
GetFilterActions	Event	Returns an array of the filter actions set for the Event object.
GetIDs	Selection	Returns 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	Shape	Returns an array of the IDs of data recordsets linked to a shape.
GetLinkedDataRow	Shape	Returns the ID of the row to which a shape is linked in the specified data recordset.
GetMatchingRowsForRefreshConflict	DataRecordset	Returns an array of IDs of data rows that may have a broken link to a specified shape after a refresh operation.
GetPrimaryKey	DataRecordset	Returns the name of the primary key column of the data recordset.
GetProperty	DataColumn	Returns the value of the data column property passed in as VisDataColumnProperties.
GetRowData	DataRecordset	Returns 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	Page	Returns an array of shapes on the page linked to a specific data recordset.
GetShapesLinkedToDataRow	Page	Returns an array of shapes on the page linked to a particular data row in a data recordset.
GetThemeNames	Document	Returns 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	Shape	Determines 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.
LinkToData	Selection, 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	DataRecordset	Refreshes the data in a data recordset that has no data connection.
RemoveHiddenInformation	Document	Removes the specified VisRemoveHiddenInfoItems items from the document.
RemoveRefreshConflict	DataRecordset	Removes all conflict information from the drawing file.
SetColumnProperties	DataColumns	Sets the properties of the specified columns to the values specified.
SetExpression	GraphicItem	Sets the value of the expression string that is part of a GraphicItem object's rule, against which shape data is evaluated.
SetFilterActions	Event	Specifies which extensions to the MouseMove event Visio will report.
SetPrimaryKey	DataRecordset	Sets the column name of the primary key column used during a refresh operation.
SetProperty	DataColumn	Sets the specified property (as VisDataColumnProperties) to the specified value.
ShapeIDsToUniqueIDs	Page	Returns an array of unique IDs (GUIDS) for shapes specified by their shape IDs.
UndoCheckOut	Document	Closes and reopens a checked-out document; deletes the private copy of the document, discarding any changes; and undoes the checkout
UniqueIDsToShapeIDs	Page	Returns 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	ApplicationSettings	Gets 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	DataRecordset	Gets or sets the command string used to query the data source.
ConnectionString	DataConnection	Gets or sets the connection string used to access an existing DataConnection object or to create a new DataConnection object.
ContainsWorkspaceEx	Document	Gets 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	DataRecordset	Returns the DataColumns object associated with the DataRecordset object.
DataColumnsAdded	DataRecordsetChangedEvent	Returns an array of the IDs of columns added to the data recordset as part of a refresh operation. Read-only.
DataColumnsChanged	DataRecordsetChangedEvent	Returns an array of the IDs of columns in the data recordset whose type changed as part of a refresh operation. Read-only.
DataColumnsDeleted	DataRecordsetChangedEvent	Returns 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, InvisibleApp	True if data features are enabled for the current instance of Visio. Read-only.
DataGraphic	GraphicItems, 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	Master	Determines whether the data graphic is visible in the Data Graphics task pane.
DataGraphicHidesText	Master	If 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.
DataRecordset	DataColumns, DataColumn, DataRecordsetChangedEvent	Returns the DataRecordset object associated with the parent object.
DataRecordsets	Document	Returns the collection of DataRecordset objects associated with the Document object.
DataRowsAdded	DataRecordsetChangedEvent	Returns 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	Document	Gets 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	Master	Returns the GraphicItems collection of the Master object. Read-only
HorizontalPosition	GraphicItem	Gets 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 Settings2007 dialog box. Read-only.
LanguageSettings	Application, InvisibleApp	Returns a reference to the Microsoft Office LanguageSettings interface. Read-only.
LinkReplaceBehavior	DataRecordset	Gets 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	DataRecordset	Gets 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	Window	Gets or sets the DataRecordset object that is selected on the active tab of the External Data window.
SelectedDataRowID	Window	Gets or sets the row ID of the selected row displayed on the active tab of the External Data window.
ShowMoreShapeHandlesOnHover	ApplicationSettings	Gets 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	DataRecordset	Returns 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 VerticalPosition setting (when set to False).
VerticalPosition	GraphicItem	Gets 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
AfterRemoveHiddenInformation	Application, Document, Documents, DrawingControl, InvisibleApp	Occurs when hidden information is removed from the document.
AfterResumeEvents	Application, InvisibleApp	Occurs after firing of events is resumed.
BeforeDataRecordsetDelete	Application, DataRecordset, DataRecordsets, Document, Documents, InvisibleApp	Fired before a DataRecordset object is deleted.
BeforeSuspendEvents	Application, InvisibleApp	Occurs before firing of events is suspended.
DataRecordsetAdded	Application, DataRecordsets, Document, Documents, InvisibleApp	Fired after a DataRecordset object is added.
DataRecordsetChanged	Application, 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, InvisibleApp	Occurs 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.
ShapeLinkAdded	Application, Document, InvisibleApp, Page, Pages, Shape	Fired after a Shape object is linked to data.
ShapeLinkDeleted	Application, Document, InvisibleApp, Page, Pages, Shape	Fired when the link between a Shape object and data is broken.
SuspendEventsCanceled	Application, InvisibleApp	Occurs 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.
VisAutoLinkBehaviors	Automatic data-linking behavior options passed to the Selection.AutomaticLink method.
VisAutoLinkFieldTypes	Field types used with automatic data-linking passed to the Selection.AutomaticLink method.
VisDataColumnProperties	Data-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.
VisFilterActions	Drag-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.
VisGraphicField	Graphic 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.
VisGraphicPositionHorizontal	Horizontal data-graphic position options passed to and returned by the GraphicItem.PositionHorizontal property.
VisGraphicPositionVertical	Vertical data-graphic position options passed to and returned by the GraphicItem.PositionVertical property.
VisLinkReplaceBehavior	Options 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.
VisPrimaryKeySettings	Primary-key settings for a data recordset, passed to the DataRecordset.SetPrimaryKey method and returned by the DataRecordset.GetPrimaryKey method.
VisRefreshSettings	Data-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.
VisThemeTypes	Theme 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	Events	An 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	Protection	Prevents application of theme colors to the shape. Corresponds to the From theme colors check box setting in the Protection dialog box.
LockThemeEffects	Protection	Prevents 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).

Conclusion

The new Automation objects and members and the new ShapeSheet cells and functions described in this article make it possible to extend the functionality of Visio programmatically to connect to data, link shapes to data, and display data graphically.

Additional Resources

For more information, see the following resources: