Insights for developers about Change Shape

Lots of customers have told us that they want to exchange one shape with another without losing the text, connections and formatting. The Change Shape feature in the new Visio gives you this functionality.

In this post, we will review the Change Shape feature and talk about the implications of the feature on shape and solution developers.

The basics

Our customers told us that they commonly build diagrams with simple shapes and later update the diagram to use more specific shapes. As an example, you might build a Basic Flowchart using only Process shapes and then realize that some of the shapes should be Decision and Start/End shapes. Another user might change their Basic Flowchart shapes into BPMN shapes.

In the past, changing from one set of shapes to another required either rebuilding the diagram, or deleting each shape (one at a time) and inserting a new shape to replace it. As part of the latter, the user had to manually copy over any customizations, such as positioning, connections, text, formatting and shape data. In the new Visio, the Change Shape feature will automatically do the replacement for you.

Change Shape on the Visio Home tab

 Change Shape is located on the Home tab and on the new Floatie that appears when you right-click on a shape.

Change Shape on the Visio Floatie menu

We explain how to use Change Shape in our article about ways to be more efficient in the new Visio.

Behind the scenes

A lot of the Change Shape fundamentals for developers are covered the in the Change Shapes in Visio 2013 post on MSDN. That article explains the Change Shape API and some of the Change Shape ShapeSheet cells. We also provide a more detailed explanation of the Change Shape API in the API in the new Visio article. In this article, we will focus on how developers can work with and customize Change Shape.

As a developer, you can think of Change Shape as a delete of an old shape and an insertion of a new shape. In fact, the operation triggers delete and insert events for solutions listening to these events. For the rest of the article, we will call the “old shape” the target shape and the “new shape” the replacement shape.

By default, local shape data, text and formatting are transferred from the target shape to the replacement shape. We also copy the local values from the Hyperlink, Layer, Protection, Alignment, Layout, 1-D Endpoint and the Shape Transform sections. None of the default shape information—the data inherited from the master—is transferred. The information must be customized and brought local to the target shape for Change Shape to copy it.

The intent of Change Shape is for the replacement shape to inherit most of the properties and behaviors of its master. Many ShapeSheet sections, like Actions, User Cells, Controls and Geometry, are never copied over, even if they have been customized. One implication of this behavior is that a replacement shape from outside a solution stencil will not take on the solution- or template-specific behaviors of the target shape after a Change Shape operation.

Customizing Change Shape using the ShapeSheet

At the shape level, there are six ShapeSheet cells that allow shape developers to control how their shapes behave during a Change Shape operation: LockReplace, ReplaceLockShapeData, ReplaceLockText, ReplaceLockFormat, ReplaceCopyCells and User.msvReplaceClass. We look at these cell values on the master of the replacement shape to determine the customized Change Shape behavior. We do not use the cell values on the target shape.

Change Shape ShapeSheet cells

Here are some examples of when you might want to use the different cells.

1. Shape data on the new shape needs to remain intact

We set ReplaceLockShapeData = TRUE for our BPMN 2.0 shapes. The BPMN 2.0 shapes shipped with the new Visio contain important shape data, such as the Loop and Task Type properties on the Task shapes. This information represents the data from the standard that is relevant to the visual look of a particular shape.

BPMN 2.0 shape data

If ReplaceLockShapeData = TRUE and we replace target shape A with replacement shape B, the shape data from shape A will not be copied over to shape B. So, for example, if we replace a Send Loop Task with a Gateway, we do not copy “LoopType = Standard” and “TaskType = Send” to the Gateway shape. These are Task attributes and are not relevant to the Gateway shape.

2. Text on the new shape needs to remain intact

If the text in your custom shapes is significant, you may not want the text of the replacement shape to take on text from the target shape. For example, if your custom shapes are computer components and have their serial numbers as text, you may want the serial number of the replacement shape to remain its original serial number after the Change Shape operation. To preserve the text, you can set ReplaceLockText = TRUE: in this case, if we replace shape A with shape B, the text from shape A will not be copied over to shape B.

3. Formatting of the new shape needs to remain intact

If you have shapes that should be a particular color or format, you may want to set ReplaceLockFormat = TRUE. For example, you might have a stencil of furniture that can be purchased with a “brown sofa” and “grey sofa”. After a Change Shape operation, you might want these colors to persist and not take on any local formatting. If ReplaceLockFormat = TRUE, the replacement “brown sofa” will remain brown, even though the target shape could have been customized with a different color. If ReplaceLockFormat = FALSE, your “brown sofa” will take on the local formatting of the target shape and may not actually be brown after the Change Shape operation.

Visio Change Shape drop down

Note that we obey the Protection section information for the shapes, so, if you had set LockFormat already, you don’t have to worry about ReplaceLockFormat.

4. Further customizing data to transfer

We provide finer control of the properties transferred through the ReplaceCopyCells cell. It specifies a list of ShapeSheet cells that should be copied from the target shape to the replacement shape. Like above, we look at this cell value on the master of the replacement shape to determine the customized Change Shape behavior. We use this cell for our Organization Chart shapes to specify a list of User cells to transfer during the Change Shape operation.

ReplaceCopyCells ShapeSheet cell on the Organization Chart shapes

5. Filtering the list of Change Shape options

In some cases, you may want to limit the shapes that can be included in a diagram using Change Shape. For example, suppose your solution supports a very specific set of shapes, and the user should not replace a solution shape with an arbitrary shape. In this case, you can add User.msvReplaceClass to all your solution shapes and set its value to the same unique identifier.

For our Organization Chart shapes, we set User.msvReplaceClass to “visOrgChart”. This means that, when an Organization Chart shape is selected, the Change Shape dropdown only shows the other Organization Chart shapes. Other shapes are filtered out of the dropdown menu, because the Organization Chart shapes are the only shapes with User.msvReplaceClass set to “visOrgChart”.

Visio Organization Chart shapes Change Shape drop down menu

6. Preventing Change Shape

In designing the Change Shape feature, we added the LockReplace, PageLockReplace and DocLockReplace cells to allow developers prevent the Change Shape operation on a shape, the page or the entire document, respectively.

As an example, we use LockReplace on our Pivot Node shape in the PivotDiagram template. This template already had a notion of “apply shape” and we did not want to confuse customers with two metaphors for providing more detailed template shapes.

Special shapes

Change Shape does not treat all Visio shapes equally. We decided that there were certain shapes that should not be replaced by an arbitrary shape, because the resulting shape would not have the characteristics that the user expected. The following list of shapes can only be replaced with shapes of the same type.

Like the User.msvReplaceClass cell, when a shape from the list above is selected, the Change Shape dropdown is filtered to only show shapes of the same type.

Change Shape for Visio Containers

List shapes, like Cross Functional Flowchart Swimlanes, cannot be replaced with any other shapes.

Image shapes of the EMF, WMF or EMZ picture formats are also not supported by Change Shape. Other image types are supported.

Change shape in your solutions

Change shape isn’t just relevant to shape developers. Solution developers should also think about using this functionality in their solutions.

First, Change Shape is an excellent replacement for the multi-shape design paradigm—the design paradigm where shapes have multiple geometries that users can toggle between using right mouse actions. In the new Visio, we converted the Container shapes from away from multi-shapes. This allowed us to create more complex geometries on each shape, while reducing concerns about shape size or complexity.

Visio container styles

The user can update the Container style from a gallery on the Container Tools Format tab.

Second, the Change Shape API provides the ability to replace one shape with another across a variety of scenarios. Before, implementing features that replaced one shape with another was complex, but now this functionality is available directly from the API. The API provides flags that can override the ShapeSheet customizations described above, so you can control programmatically whether text, shape data and/or formatting is transferred. The API is explained in more detail in the API in the new Visio article.

Last, ChangeShape supports the BeforeReplaceShapes, QueryCancelReplaceShapes and AfterReplaceShapes events. This gives developers the option to customize how Change Shape works in their solutions. You can cancel the event and perform your own actions, or you can perform your own post-processing after the operation completes. As an example, for Organization Chart shapes, we decided to keep the multi-shape design paradigm for position types: the solution cancels the Change Shape operation and changes the position type in solution code.


Change Shape is one of our most exciting end user features in the new Visio and makes it much easier to update the shapes in your diagram. The default behavior transfers a small amount of user-customized information from the old shape to the new shape. There are, however, lots of options to customize the behaviors of Change Shape depending on the situation. Developers can also use the new API to write code that uses Change Shape to exchange shapes programmatically.

Try it out and let us know what you think!