Chapter 9. Automating Structured Diagrams

In the previous chapters, we learnt how to import data and display information graphically, and even how to validate the structure of a diagram. However, there are many scenarios when generating all or part of a diagram from data can save hours of manual layout work. In this chapter, we will look into ways of generating structured diagrams from data. This will include dropping specific shapes for specific data values, connecting shapes together, and placing them into containers and lists. Finally, we will learn how to associate callouts with shapes.

This chapter includes copious VBA macros, which contain the principles for actions in any other coding language.

In this chapter, we will learn the following:

• Using a specific Master shape

• Dropping and linking shapes to data

• Connecting shapes from data

• Adding data-linked shapes to containers

• Adding data-linked shapes to lists

• Adding callouts to shapes

Structuring diagrams overview

The Structured Diagram API was introduced in Visio 2010 to provide programmatic access to new features and shape types. The Structured Diagram API classes, properties, and methods are italicized in the following partial Visio API object model:

This chapter includes example code of some of the most useful parts of the Structured Diagram API, but, for brevity, does not include thorough error checking.

Note

For more information about the Structured Diagram API, see https://blogs.msdn.microsoft.com/visio/2010/01/27/container-list-and-callout-api-in-visio-2010/.

Enabling diagram services

Using Visio manually always triggers the structured diagram behaviors, where applicable. However, it may not always be desirable via automation code, so the default is for no structured diagramming behaviors. Fortunately, they can be selectively enabled using Structured Diagram API. Therefore, most of the code examples in this chapter are, or should be, topped and tailed with the following...

Selecting a Master shape to drop

A Master object must be obtained before it can be dropped onto a page using code. Simply knowing the name of a desired Master is not enough because the Master may not exist in the Document Stencil yet. Also, there may be more than one Master with the same name on any opened stencil, so the stencil name may also be required. In fact, the active Document may have a number of docked stencils, so they should be checked first. Then, the Visio Application may have a number of different stencil documents open. Lastly, the stencil may not even be open in Visio, so the stencil may need to be opened, but that is left for the accompanying code for this book.

The caption that appears on the header bar of a stencil is either the mapped long name or title of the stencil, if there is one, otherwise it displays the name without the file extension. All the built-in stencils have terse filenames that are mapped to longer names that are displayed in the UI. These mappings are...

Dropping and linking shapes to data

It is often necessary to drop multiple shapes and link each one of them to a different row in DataRecordset. For example, the following screenshot shows a document with an External Data window that contains Personnel DataRecordset. The diagram requires the Sales team to be added to the page.

The following function, GetDataRecordset(), looks for DataRecordset with the given name in the specified document and returns it:

This function is used by the following sub-function, DropManyLinked(), filters the Personnel DataRecordset, gets the Person Master from the open Work Flow Objects stencil, and drops data-linked copies in a line along the bottom of the page.

The last line calls the sub-function, ApplyDataGraphics(), shown in the following screenshot. This is a workaround for an issue that currently exists in Visio 2016. Specifically, there is a reserved User-defined Cell, named User.msvLastAppliedDataGraphic, in DocumentSheet that contains the name of the Data...

Connecting shapes from data

The example Personnel DataRecordset has a Reports To column that is used by Organization Chart Wizard to create a hierarchy by connecting the shapes together. The data that connects two shapes together does not need to be in the same DataRecordset, especially if there are many-to-many relationships.

A lot of the VBA code in this chapter make increasing use of arrays. However, the VBA IsArray() and IsEmpty() functions do not really report an empty array. Therefore, the following function, IsEmptyArray(), will return True or False by forcing an error if necessary:

Also, much of the code herein needs to get the index of DataColumn. However, the DataColumn object does not have an index property. Therefore, the following function, GetColumnIndex(), returns the index or -1 if the specified column name does not exist in DataRecordset:

Now that the helper functions are defined, they can be used in the sub-function LinkShapes() to iterate through the shapes on the active...

Adding data-linked shapes to containers

Containers group shapes together visually. The normal user adds a container to the existing shapes using the Insert | Diagram Parts | Container button. The same action can be repeated in code using the Page.DropContainer() method. The container shape is added to the page and encloses the target shapes.

An alternative is to use the Shape.ContainerProperties.AddMember() method, where Shape is a container shape. The container can then expand to enclose the target shapes, which remain in their current positions.

The final alternative action is to move the target shapes into an existing container shape. In the following screenshot, the Person shapes are on the outside of the Sales container:

The following sub-function, DropShapesInContainer(), finds all the relevant containers by creating a selection of all the shape instances of the Belt Master. It gets the text of each container because this is the name of a department. It then finds all the rows from Personnel...

Adding data-linked shapes to lists

Lists are a special type of container. Each item in a list is ordered from left to right, right to left, top to bottom, or bottom to top. These are the settings that can be applied to the list. In the following screenshot, the Sales container has been changed to a list ordering from left to right:

The code is almost identical for DropShapesInContainer(), except that the rows that move the Person shapes into the center of the container are replaced with the action to insert them into a list.

This results in the Person shapes being neatly aligned within the list container, as shown in the following screenshot. There is no need to lay out the shapes, of course.

In reality, the Person shapes will be ordered according to some rule, rather than just looping through DataRecordset.

Note

For more uses of lists in Visio diagrams, see http://blog.bvisual.net/2014/12/31/get-scrabbled-with-visio/.

Adding Callouts to shapes

There is a built-in stencil called Callouts in the Visio Extras category, but the Callouts introduced as part of Structured Diagram API are something different. These are a special type of Shape that have some programmatic control. Any shape can have many Callouts associated with it. The names of Callout Masters in the built-in stencil can be read by moving the mouse over them in the Insert | Diagram Parts | Callout drop-down gallery, as in the following screenshot:

The following code, AddCallouts(), gets a reference to the Thought Bubble callout from the built-in stencil. It then loops through all the shapes in the active page that are linked to Personnel DataRecordset. It drops a new shape instance of the Callout Master and associates it with the Person shape, and inserts the name of Person Shape as text.

The resultant diagram is shown in the following screenshot:

Callouts can be used for comments or notes, or even as additional placeholders for information held...

Summary

In this chapter, we learnt how to create structured diagrams with data values found within DataRecordsets. We learnt how to connect shapes, add shapes to containers and lists, and how to associate Callouts.

In the next chapter, we will learn how to make these data-driven diagrams available to others to view and interact with.