API in the new Visio | Microsoft 365 Blog

September 12, 2012

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.

Shape.ReplaceShape(MasterorMasterShortcutToDrop, ReplaceFlags)

Returns a new instanced shape which has replaced the given shape.

Arguments:

MasterorMasterShortcutToDrop
Specifies the master or the master shortcut to use as the replacement shape.

ReplaceFlags
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.

// In the following C# code, we are opening this diagram along with the updated Workflow Steps stencil
// and we are selecting the first page
Visio.Document workflowStepsStencil = GlobalVars.Application.Documents.OpenEx(_"WFSTME_U.VSSX", Visio.VisOpenSaveArgs.visOpenHidden );
Visio.Document diagram = GlobalVars.Application.Documents.Open(documentPath);
Visio.Page page = diagram.Pages[1];

// Here, we are setting up the shapes that we wish to replace, along with the masters that we wish to replace them with from the Workflow Steps stencil:
Visio.Shape processShape = page.Shapes["Process"];
Visio.Shape decisionShape = page.Shapes["Decision"];
Visio.Shape subprocessShape = page.Shapes["Subprocess"];
Visio.Shape custom3Shape = page.Shapes["Custom 3"];
Visio.Shape endShape = page.Shapes["Start/End"];

Visio.Master issueMaster = workflowStepsStencil.Masters["Issue"];
Visio.Master requestMaster = workflowStepsStencil.Masters["Request"];
Visio.Master rejectMaster = workflowStepsStencil.Masters["Reject"];
Visio.Master approveMaster = workflowStepsStencil.Masters["Approve"];
Visio.Master endMaster = workflowStepsStencil.Masters["End"];

// Finally, we replace the existing shapes with new instanced shapes from the specified masters:

processShape.ReplaceShape(issueMaster);
decisionShape.ReplaceShape(requestMaster, 8);
subprocessShape.ReplaceShape(rejectMaster, 3);
custom3Shape.ReplaceShape(approveMaster);
endShape.ReplaceShape(endMaster);

This yields the following result:

Visio diagram after change shape operation

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.

Shape.ChangePicture(FileName, ChangePictureFlags)

Replaces the given picture shape with a new picture.

Arguments:

FileName
Specifies the full path of the replacement picture.
ChangePictureFlags
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.

Visio comment

The follow objects, methods, and properties are used to work with comments on shapes and pages.

Shape.Comments Property

Returns a Comments object listing all comments associated with the given shape.

Page.Comments Property

Returns a Comments object listing all comments associated with the given page and all shapes contained in the given page.

Page.ShapeComments Property

Returns a Comments object listing all comments associated with all shapes contained in the given page.

Document.Comments Property

Returns a Comments object listing all comments associated with all pages and all shapes contained in the given document.

Comment Object

An object containing properties to reference a comment’s author name, text, and creation date, amongst others. Includes a method to delete the comment.

Comment.Delete()

Deletes the Comment object.

Comments Object

An object containing an indexed list of Comment objects. Includes methods to add and delete all comments from the list.

Comments.Add(Comment)

Appends a string as a new Comment object to the end of the Comments object list.

Arguments:

Comment
A string specifying the text of the added comment.

Comments.DeleteAll()

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.

Duplicate page

The following method evokes the Duplicate Page feature on a given page.

Page.Duplicate()

Returns a new page within the same document that is a copy of the given page.

Summary

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.