Our previous posts have discussed some of the great end user features we’ve added to the new Visio. For developers, the new Visio supports programmatic access for many of its new features. The new Visio API contains methods that let developers change shapes and pictures, add comments, duplicate pages, and apply themes.
In this blog post, we will introduce some of the new API by providing brief descriptions about the methods, properties, and objects. We will also see some of them in action using examples. This is not meant to be a complete reference; you can view a full list of all new API in the What’s new for Visio 2013 developers article on MSDN.
Working with Change Shape
The new Visio supports a new Change Shape feature, which allows for the seamless replacement of an existing shape or selection of shapes in your document with any other shape in an open stencil. The following method evokes the Change Shape feature on a given shape.
Returns a new instanced shape which has replaced the given shape.
Specifies the master or the master shortcut to use as the replacement shape.
An optional argument that specifies a set of enumerations determining whether the given shape’s text, data, and/or formatting are carried over to the new instanced shape. By default, the text, shape data and formatting are copied from the old shape to the new shape only if they have been customized in the diagram and are different from their master. The enumerations can be summed to produce a combination of the specified enumeration behaviors.
The specific enumerations are:
0: Use the behavior specified by the given shape’s ShapeSheet cells ReplaceLockText, ReplaceLockShapeData and ReplaceLockFormat. A “0” value in any of these three ShapeSheet cells indicates that shape text, data, or formatting (respectively) are transferred to the new instanced shape. A “1” value indicates that the respective objects are not transferred. 1: Override the given shape’s ShapeSheet flags. Allow the given shape’s text, data, and formatting to transfer to the new instanced shape during the Change Shape operation 2: Override the given shape’s ReplaceLockText ShapeSheet flag. Prevent the given shape’s text from transferring during the Change Shape operation. This enumeration takes priority over enumeration “1” if combined. 4: Override the given shape’s ReplaceLockData ShapeSheet flag. Prevent the given shape’s data from transferring during the Change Shape operation. This enumeration takes priority over enumeration “1” if combined. 8: Override the given shape’s ReplaceLockFormat ShapeSheet flag. Prevent the given shape’s formatting from transferring during the Change Shape operation. This enumeration takes priority over enumeration “1” if combined.
Let’s try it out
Using the method above, we will replace the shapes on this Basic Flowchart diagram with shapes from our updated Workflow template.
Note: In the below code snippets, the Visio namespace is an abbreviation of Microsoft.Office.Interop.Visio. The meanings of most other variables should be apparent from the context.
This yields the following result:
You’ll notice that the formatting was lost when we replaced the Decision shape with the Request shape. The reason is that we set the ReplaceFlags argument’s enumeration to “8”, and thus the formatting did not transfer.
You’ll also notice that the text was lost when we replaced the Subprocess shape with the Reject shape. The ReplaceFlags argument’s enumeration “3” is an additive combination of enumerations “1” and “2”. Enumeration “1” ensures that text, data, and formatting are transferred; however, enumeration “2” specifically forbids text from transferring and takes priority over “1”. Thus, data and formatting were transferred, but text was not.
Working with Change Picture
The new Visio allows any existing picture shape to be changed to a new picture. The following method evokes this functionality on a given picture shape.
Replaces the given picture shape with a new picture.
Specifies the full path of the replacement picture.
An optional argument that is currently unused and is reserved for future implementation.
Working with Commenting
The new Visio includes a new commenting framework, where comments can now be associated with a shape or a page.
The follow objects, methods, and properties are used to work with comments on shapes and pages.
Returns a Comments object listing all comments associated with the given shape.
Returns a Comments object listing all comments associated with the given page and all shapes contained in the given page.
Returns a Comments object listing all comments associated with all shapes contained in the given page.
Returns a Comments object listing all comments associated with all pages and all shapes contained in the given document.
An object containing properties to reference a comment’s author name, text, and creation date, amongst others. Includes a method to delete the comment.
Deletes the Comment object.
An object containing an indexed list of Comment objects. Includes methods to add and delete all comments from the list.
Appends a string as a new Comment object to the end of the Comments object list.
A string specifying the text of the added comment.
Deletes all Comment objects from the Comments object.
Working with Duplicate Page
The new Visio supports a new Duplicate Page feature, which allows for the replication of any existing page in a document. Duplicate Page will copy the given page and all contained shapes, and return the copy as a new page within the same document.
The following method evokes the Duplicate Page feature on a given page.
Returns a new page within the same document that is a copy of the given page.
We hope this brief look at some of our new API was helpful. We’ll be covering API support for our new themes, variants, and styles feature in a future post. As a reminder, you can view a full list of all new API in the What’s new for Visio 2013 developers article on MSDN. We’re interested to hear what developers think of this API functionality. Please use the Send a Smile feedback tool or leave a comment below.