Adding Structure to Diagrams in Visio 2010

Summary:  Learn how to organize the shapes in a Microsoft Visio 2010 diagram by using containers, lists, and callouts, by working with built-in structured-diagram shapes, or by creating new structured-diagram content.

Applies to: Office 2010 | SharePoint Server 2010 | Visio 2010 | Visio Premium 2010

In this article
Introduction
Using Structured-Diagram Shapes in Diagrams
Building Custom Structured Diagram Shapes
Using Automation with Structured-Diagram Shapes
Conclusion
Additional Resources

Applies to: Microsoft Visio 2010

Published: August 2010

Provided by: Mark Nelson, Microsoft Corporation

Contents

• Introduction

• Using Structured-Diagram Shapes in Diagrams

• Building Custom Structured Diagram Shapes

• Using Automation with Structured-Diagram Shapes

• Conclusion

• Additional Resources

Introduction

Users are creating and maintaining more complex Visio diagrams than in the past. The number of pages in a document, the number of shapes on a page, and the amount of information in shapes are increasing for a wide range of diagram types. In addition to increasing information density, users are capturing more of the logical definition of their processes, projects, and systems. They are moving beyond diagrams as pictures and moving toward diagrams as semantic representations of their business.

As complexity grows, the need for organization of the diagram information grows, as well. Visio users employ a number of strategies to keep their diagrams organized and understandable. Common solutions include arranging and aligning shapes, applying similar formatting to related shapes, and drawing boxes around shapes to define logical groups. While these solutions do improve readability, they can require a lot of work to set up and maintain.

Take the example of drawing a box around related shapes. In previous Visio releases, users would draw a rectangle around some shapes, choose Send to Back to move it behind the shapes, add a text label and position it near the rectangle edge, and finally group everything to keep the shapes together. Many steps are required to set up the relationship. Additionally, it becomes difficult to access the individual shapes, and the user must ungroup and regroup the diagram contents every time they change.

Structured Diagrams

Visio 2010 introduced structured diagrams, which enable you to organize the contents of diagrams in logical relationships. A structured-diagram document treats shapes as more than a collection of objects on a page. With structured diagrams, shapes can have logical relationships with each other. Visio 2010 uses its awareness of these relationships to introduce a set of interaction behaviors. These behaviors facilitate the construction and maintenance of shape relationships, making information organization in Visio easier and less time consuming.

Structured-Diagram Feature Set

There are three types of structured-diagram relationships available in Visio 2010, as shown in Figure 1, and there is a Visio 2010 feature for each relationship type:

• Containment—Shapes can be visually bounded by another shape. The containers feature allows users to set up and maintain containment relationships.

• Order—Shapes can be arranged next to each other in a specified sequence. The lists feature allows users to manage order relationships.

• Association—Shapes can describe or annotate other shapes. The callouts feature allows users to set up and maintain association relationships.

Figure 1. Structured-diagram shape relationships

Containers, lists, and callouts make up the core feature set for structured diagrams. These features enable you to create logical relationships between specified shapes in a diagram. These features are discussed in the next section. There are also a series of platform features in Visio 2010 that enhance the behaviors of containers, lists, and callouts to make them even easier for users and shape designers to work with. Those features are discussed later in the article.

Using Structured-Diagram Shapes in Diagrams

This section describes how end users can work with containers, lists, and callouts in structured diagrams.

Working with Containers

The containers feature in Visio 2010 makes it easy to add a visual boundary or container around shapes, including displaying a label. Visio does all the work to maintain the relationship between the container and its contents. To add a container to the diagram, first select the shapes to be contained. Then choose the Container command from the Insert tab of the ribbon. A gallery appears with several different container styles, as shown in Figure 2. Click a style to add the container to the diagram.

Figure 2. Container gallery

 

Container Behaviors

The shapes inside the container are not grouped into a single shape, so users have direct access to continue working with them, as shown in Figure 3. Users can add or remove shapes by dragging them into or out of the container. When users drag a shape, an orange highlight appears around the container to indicate that Visio will make the shape a member of the container. The orange highlight also appears when users select an existing member of a container. The container can automatically grow or shrink as needed to fit the contents. Moving, copying, or deleting the container will move, copy, or delete the contents, as well.

Figure 3. Individual shapes in a container

 

Customization

Users can format containers just like regular shapes. In particular, users can change the alignment of the heading by using the text alignment buttons on the Home tab of the ribbon. There is also a contextual tab (Container Tools, shown in Figure 4) that allows further customization of containers. Users can control how tightly the container bounds its contents by using the Margins or Fit to Contents command. Users can switch between different visual styles and change the position of the container heading. It is also possible to lock the container to prevent shapes from being added or deleted.

Figure 4. Container Tools tab

 

Selection

Because the shapes in a container are not grouped, users can directly click shapes to select them. There is also a command on the Container Tools contextual tab and on container shortcut menus (as shown in Figure 5) to select all the shapes in a container at once. Users can select the container itself by clicking the container heading or geometry. Typically, users cannot select containers by clicking their interiors (for more information, see the NoQuickDrag section).

Figure 5. Selecting container contents

 

Disbanding Containers

When a container is moved, copied, or deleted, the member shapes are also moved, copied, or deleted. Because deleting a container deletes the members of the container, too, there is a Disband Container command in the Container Tools contextual tab and the container shortcut menu. This command deletes the container without deleting the contents.

Boundary Shapes

Although members of containers are normally placed completely inside the container boundary, it is also possible to put shapes directly on the container boundary, as shown in Figure 6. The shapes are still considered members of the container, but they behave differently during resize actions. To put a shape on the boundary of a container, simply drag it there. Notice the difference in highlighting feedback between dragging a shape into a container (the entire boundary is highlighted) versus onto the boundary (just the single container edge is highlighted). Once a shape is on the container boundary, it will move with that boundary. Users can resize the container and the shape will stay on the boundary.

Figure 6. Putting a shape on a container boundary

Working with Lists

The lists feature in Visio 2010 keeps shapes arranged in a sequence. Lists are a special form of container, providing many of the same capabilities as containers but adding the automatic arrangement of member shapes. Unlike in the containers and callouts features, there is no way for end users to create a generic new list. However, a number of diagrams and features in Visio 2010, including the following, use lists to arrange shapes:

• Cross-functional flowchart—This diagram (shown in Figure 7) is effectively a list of container shapes. Each swimlane is a container, and all the swimlanes belong to a list. This makes inserting, arranging, and reordering swimlanes simple.

  Figure 7. Cross-functional flowchart

  

   

• Data graphic legend—This feature (shown in Figure 8) uses a nested combination of list and container shapes. An outer list includes containers for each data field in the legend. The containers have an inner list that includes each of the graphic symbols used to represent that data field.

  Figure 8. Data graphic legend

  

   

• Wireframe diagram—A number of the user-interface elements in a wireframe diagram (shown in Figure 9) arrange shapes in lists. For example, menu bars and drop-down menus manage individual menu shapes.

  Figure 9. Wireframe diagram

  

   

List Behaviors

As with containers, lists allow users to add and remove shapes by dragging them in or out of the list shape. An orange highlight rectangle appears around the list shape to denote membership, and an orange insertion bar indicates the specific position that a new shape will occupy. In addition to dragging shapes into a list, the user can click a blue insertion triangle (shown in Figure 10) on either side of the list to insert a new shape at the highlighted position. You can reorder shapes in a list by dragging or by using the arrow keys on the keyboard.

Figure 10. Inserting shapes into a list

Visio automatically keeps the members of a list properly positioned. Lists have properties for direction, spacing between members, and shape alignment that determine where members are placed. Some list shapes expose the same Container Tools contextual tab that container shapes use to provide options for margins and visual style. Moving, copying, or deleting a list will also move, copy, or delete the list members.

Working with Callouts

A callout (shown in Figure 11) is an annotation on a diagram that provides more information about a shape. Callouts are Visio shapes themselves, which differentiates them from other forms of annotation such as comments. Callouts are part of the visible drawing, and you can edit and format them like any other shape. A callout points at or references another shape, which is called the target of the callout. It is placed close to its target and may have a line connected to it. The connecting line is known as a leader or callout line.

Figure 11. Callout

To add a callout shape in Visio 2010, select the target shape on the page, and then click Callout on the Insert tab, as shown in Figure 12. The Callout gallery on this tab has many different styles of callouts. Hover over a style to see it applied as a Live Preview, and then click the style to add the callout. The callout appears slightly above and to the right of the target shape.

Figure 12. Callout gallery

Callout Behaviors

Callout shapes are not new to Visio 2010, but Visio 2010 gives callout shapes special behaviors. When a target shape is moved, copied, or deleted, any callouts attached to the shape are moved, copied, or deleted, too. Thus callouts stay with their target shapes, though users can reposition the callout to any offset from its target. Callout shapes are also designed to be displayed in front of other shapes. Even if newer shapes that overlap with callouts are added to a page, the callouts appear in front.

Customization

There are additional options for the visual style of callout shapes, which you can access by right-clicking a callout, as shown in Figure 13. The Callout Style submenu allows users to switch to a different geometric style and has the same choices as the Insert Callout gallery in the ribbon. The Orientation submenu determines which side the callout’s leader attaches to. The Callout Line submenu controls the visibility and placement of the leader. The Resize with Text submenu determines whether the callout shape resizes to fit the amount of text in the shape.

Figure 13. Callout shortcut menu

Building Custom Structured Diagram Shapes

While there are many built-in container, list, and callout shapes in Visio 2010, you can use any two-dimensional (2-D) shape as a container, list, or callout. This section describes how shape designers can create their own structured-diagram shapes.

Custom Containers

To designate any shape as a container, list, or callout, a shape designer needs to add only one user-defined cell called User.msvStructureType to the ShapeSheet. For the value, enter "Container", "List", or "Callout", as appropriate. This setting tells Visio that the shape is a structured-diagram element and adds many of the structured-diagram behaviors to the shape. In Figure 14, a rectangle shape is transformed into a container shape by adding the User.msvStructureType cell and setting it to "Container".

Figure 14. Creating a custom container

Any shape that has a value of "Container" for the User.msvStructureType cell is treated by Visio as a container, though Visio also requires the shape to be 2-D and have a value of 0 for the Angle cell. There are additional settings available to customize the appearance and behavior. Table 1 describes the ShapeSheet cells that define these container properties, several of which can be configured in the Container Tools contextual tab in the ribbon.

Table 1. ShapeSheet container properties

Cell name	Description
User.msvSDContainerMargin	The distance between the container boundary and member shapes.
User.msvSDContainerResize	The automatic-resize behavior for the shape: 0 = No automatic resize. 1 = Expand as needed. 2 = Always fit to contents.
User.msvSDContainerStyle	A one-based index value for the current visual style of the container.
User.msvSDContainerStyleCount	The total number of visual styles that the container supports.
User.msvSDHeadingStyle	A one-based index value for the current visual style of the container heading.
User.msvSDHeadingStyleCount	The total number of visual styles that the container heading supports.
User.msvSDContainerLocked	A Boolean value that prevents membership changes in the container.
User.msvSDContainerRequiredCategories	A semicolon-delimited list of category names. Other shapes must have at least one matching name to be allowed as container members.
User.msvSDContainerExcludedCategories	A semicolon-delimited list of category names. Other shapes with at least one matching name are disallowed as container members.
User.msvSDContainerNoHighlight	A Boolean value that suppresses the container highlighting when member shapes are selected or added to the container.
User.msvSDContainerNoRibbon	A Boolean value that hides the Container Tools contextual tab in the ribbon for this container.
User.msvSDContainerHeadingEdge	A string that designates the location of the interior of the container from the perspective of the container heading. Must be "Left", "Right", "Top", or "Bottom".
User.msvSDMembersOnHiddenLayer	A Boolean value that determines whether Visio severs container relationships when the container or member is placed on a hidden layer. If True, Visio allows relationships to exist on the hidden layer. If False, Visio severs the relationships.

Creating a Visual Style

By default, a custom container shape does not have any container or heading styles available in the Container Tools tab, as shown at the top of Figure 15. Styles are a way to offer different looks for the container by using a combination of geometry and formatting changes. You can define visual styles for a container shape by using the User.msvSDContainerStyle, User.msvSDContainerStyleCount, User.msvSDHeadingStyle, and User.msvSDHeadingStyleCount cells (that is, the cells that contain "Style" and "Count" in their names). Use the Count cells to tell Visio how many styles a shape supports for the overall container or for the heading. Then determine what ShapeSheet cells should be set for each style. Put formulas in each of these cells that depend on the value of the Style cells. Visio will check the style count and populate the ribbon galleries (as shown at the bottom of Figure 15) with each style defined by the container shape. When the user chooses a new style from the gallery, Visio puts that style index back into the Style cells to update the look of the container.

Figure 15. Adding styles for a container

The container shapes in Visio 2010 vary in complexity. The containers in the Insert Container gallery have many visual styles and lots of formulas to change the appearance of the shapes. There are some simpler examples in the wireframe shapes, which define just a few styles each.

Controlling Container Membership

Visio 2010 introduces the concept of shape categories to refine the membership behaviors of containers. This is the mechanism used by features such as cross-functional flowchart and data graphic legend to ensure that only the right kinds of shapes participate in the list and container behaviors. You can restrict container shape membership by defining a required or excluded shape category. For this to work, a prospective member shape must have a user-defined cell called User.msvShapeCategories in its ShapeSheet. The prospective shape lists one or more category names in a semicolon-delimited string. To allow only a specific category of member shape, you can set that category name in the container's User.msvSDContainerRequiredCategories cell. To allow most shapes as members but specifically exclude a category, you can set that category name in the container's User.msvSDContainerExcludedCategories cell. (Prospective shapes that have no categories defined will not be allowed in a container with required categories, and they will always be allowed in a container with excluded categories. Shapes that have some categories that are included and others that are excluded will be excluded from a container.)

Creating a Heading Subshape

The heading of a container is simply the container shape’s text for basic containers. However, it is possible to achieve more sophisticated visual styles if the heading becomes its own shape. For this construction, the container becomes a group and the heading is added as a subshape of the group. The primary benefit is that Visio can account for the heading subshape in sizing and layout operations to avoid putting member shapes on top of the heading. To designate a subshape as a heading for the container, add the cell User.msvStructureType to the subshape and give it the value "Heading". Also set the User.msvSDContainerHeadingEdge cell in the subshape. This cell tells Visio how the heading is positioned relative to the interior of the container. For example, if the heading is near the left edge of the container, the correct value for the cell is "Right" (regardless of the heading’s angle). The interior of the container is on the right side of the heading.

Custom Lists

Any shape that has a value of "List" for the User.msvStructureType cell is treated by Visio as a list. A list orders and arranges its member shapes automatically. Note that lists are also considered to be containers, and they have similar capabilities such as automatically moving, copying, or deleting member shapes. All of the previously mentioned container cells apply to list shapes. Table 2 describes the ShapeSheet cells that define additional list properties.

Table 2. ShapeSheet list properties

Cell name	Description
User.msvSDListAlignment	The alignment of list member shapes. For vertical lists: 0 = Left 1 = Center 2 = Right For horizontal lists: 0 = Top 1 = Middle 2 = Bottom
User.msvSDListDirection	The direction that the list arranges list member shapes: 0 = Left to right 1 = Right to left 2 = Top to bottom 3 = Bottom to top
User.msvSDListSpacing	The distance between the edges of list members.
User.msvSDListItemMaster	The name or UniqueID of the master shape to create an instance of for Insert commands. The value must be placed inside a USE() function.
User.msvSDListNoReorder	A Boolean value that prevents the reordering of list members. The list must also be locked by setting User.msvSDContainerLocked to True for this setting to have any effect.
User.msvSDListRequiredCategories	A semicolon-delimited list of category names. Other shapes must have at least one matching name to be allowed as list members.
User.msvSDListExcludedCategories	A semicolon-delimited list of category names. Other shapes with at least one matching name are disallowed as list members.

Specifying an Insertion Shape

There are several ways to add a shape to a list: dragging and dropping the shape, clicking the blue insertion triangle that appears near the list edge, or right-clicking an existing member and inserting a shape. Clicking the insertion triangle and right-clicking to insert a shape both use the User.msvSDListItemMaster cell to determine what shape to add to the list. The name of the master is placed in quotes inside a USE() function (for example, USE("List member master")). If no shape is specified in User.msvSDListItemMaster, Visio will duplicate an adjacent shape in the list when inserting the shape.

It is also possible to automatically populate the list with some member shapes when the list is first dropped on the page. To do this, put the following formula in the EventDrop cell of the list, repeating the DOCMD(2270) once for each member to be added:

IF(LISTMEMBERCOUNT()=0,DOCMD(2270)+DOCMD(2270)+DOCMD(2270),0)

2270 is the command for inserting before an item in a list (visUiCmds.visCmdListInsertBefore). It is also possible to use 2271, the command for inserting after an item in a list (visUiCmds.visCmdListInsertAfter).

Controlling List Membership

Lists have their own cells to govern list membership. Use the User.msvSDListRequiredCategories and User.msvSDListExcludedCategories cells to restrict what shapes can become list members. Because lists are also containers, it is possible for shapes to become container members of the list. The standard User.msvSDContainerRequiredCategories and User.msvSDContainerExcludedCategories cells determine this behavior. By default, Visio will attempt to add a shape to a list as a list member, but if that fails it may try to add it as a container member. The difference between a list member and a container member is that only list members will be arranged by the list and affect its size. Shape designers should manage both sets of membership cells to ensure the right results.

Custom Callouts

Any shape that has a value of "Callout" for the User.msvStructureType cell is treated by Visio as a callout. Callout shapes must also have a control handle with the Controls row named Controls.Association. Visio manages the relationship with the callout’s target shape by means of this row in the ShapeSheet. Table 3 describes the ShapeSheet cells that define additional callout properties.

Table 3. ShapeSheet callout properties

Cell Name	Description
User.msvSDCalloutNoHighlight	A Boolean value that suppresses the highlighting on the callout target shape
User.msvSDTargetIntersection	The location, in page coordinates, of the intersection between the geometric boundary of the target shape and a virtual line drawn from the center of the callout to the center of the target shape. This is a read-only cell set by Visio.

Exposing Custom Shapes to Users

As with any custom shape, shape designers create Visio masters by dragging them into a stencil. Users can then open this stencil as part of the document workspace and drag the shapes onto their diagram. This is still the recommended method for deploying custom structured-diagram shapes. Visio 2010 also provides a way to expose custom containers and callouts in the ribbon as described in the following paragraphs.

Showing Custom Shapes in the Insert Container Gallery

Visio provides several built-in container shapes in the Insert Container gallery located on the Insert tab of the ribbon. It is possible to override this set of shapes by creating a specially named stencil that contains alternate container shapes. Create a stencil named _CONTAIN.vss and place it in the user’s My Shapes folder.

Showing Custom Callout Shapes in the Insert Callout Gallery

Visio provides several built-in callout shapes in the Insert Callout gallery located on the Insert tab of the ribbon. It is possible to override this set of shapes by creating a specially named stencil that contains alternate callout shapes. Create a stencil named _CALLOUT.vss and place it in the user’s My Shapes folder.

Platform Capabilities for Structured-Diagram Shapes

While many of the capabilities of containers, lists, and callouts are defined by means of custom user-defined cells, there are some generic shape features that you can use to enhance the behaviors of structured-diagram shapes.

DisplayLevel

Typically in Visio, the most recently added shape is shown on top of the other shapes on the page. To change this display order (z-order), users can use commands such as Send Backward or Bring Forward, which are found in the Arrange group on the Home tab. Because container shapes are intended to be positioned behind other shapes, and callout shapes are intended to be positioned in front of other shapes, a new capability was added to Visio 2010 to avoid the need for constant display-order corrections.

The DisplayLevel cell in the ShapeSheet, as shown in Figure 16, allows a shape designer to define a z-order band for a shape. Visio automatically displays a shape behind any shape that has a higher DisplayLevel value and in front of any shape that has a lower DisplayLevel value. The DisplayLevel value can range from -32767 to 32767. By default, shapes have a DisplayLevel value of 0. Visio’s built-in containers use a DisplayLevel value of -25000. Visio’s built-in callouts use a DisplayLevel value of 25000.

Figure 16. ShapeSheet DisplayLevel cell

DisplayLevel allows Visio to automatically drop new shapes into the desired display-order position on the diagram. You can still use the ordering commands to move shapes forward and backward. However, the BringToFront and SendToBack commands behave differently. Invoking one of these commands once only moves a shape to the top or bottom of its z-order band. The command must be invoked a second time to move a shape out of its band to the true top or bottom of the z-order.

NoQuickDrag

When shapes completely overlap in a diagram, it can be difficult for users to select the shape they intend to. Clicking repeatedly on a stack of shapes will cause Visio to select each one in turn, but this means that the shape selected when clicking is dependent on the previous selection. In the case of custom containers, member shapes within the container can be hard to select. Users can accidentally select the container by clicking the member or by attempting to clear the selection by clicking just outside the member shape. Visio also has a behavior where users can click once and initiate a drag action without first selecting the shape. Thus users may inadvertently click and drag a container when attempting to lasso-select the container’s contents.

Visio 2010 introduces a new ShapeSheet cell that eliminates these problems by designating the filled geometry of a shape as unselectable. This behavior is controlled by the NoQuickDrag cell, shown in Figure 17. When NoQuickDrag is True, clicking the filled region of a shape will not result in selecting or dragging the shape. Visio treats the region as unfilled for the purpose of selection. Such shapes can still be selected by clicking directly on the geometry outline, clicking the shape’s text, or by using a lasso around the shape. Visio’s built-in container shapes have a NoQuickDrag value of True for their interior (but not for their headings).

Figure 17. ShapeSheet NoQuickDrag value

 

Custom Right-Click Submenus

Shapes that have multiple visual styles or parameter-driven appearances often expose their settings as right-click actions on a shortcut menu. Visio has long supported custom Actions for shapes, but all actions were exposed as top-level menu items. Visio 2010 adds support for custom actions in submenus (shown in Figure 18), which allows shape designers to better organize their commands.

Figure 18. Submenu

An Action row is designated as a submenu by setting the FlyoutChild cell to True. Visio will display that row as a submenu of the closest previous Action row where FlyoutChild is False. Figure 19 shows the Actions section in the ShapeSheet.

Figure 19. ShapeSheet Actions section

 

ShapeSheet Functions for Structured-Diagram Relationships

Visio 2010 introduces a number of functions for working with shape relationships.

Table 4 shows the functions that return a sheet reference, or a reference to a shape. This return value can then be used to call another function (for example, CALLOUTTARGETREF()!HASCATEGORY("Category")).

Table 4. Functions that return a sheet reference

Function	Description
CALLOUTTARGETREF()	Returns a sheet reference to the target shape that this callout is associated with.
CONTAINERSHEETREF(Index, Category)	Returns a sheet reference to the container shape that this shape is a member of. This function has the following parameters: Index—A one-based value that specifies which parent container to return, where the topmost container is ordered first. Category—The category of the container. If this parameter is specified, the container must have that category for the container to be returned.
LISTSHEETREF()	Returns a sheet reference to the list container shape that this shape is a member of.

Table 5 shows the functions that return the number of related shapes.

Table 5. Functions that return the number of related shapes

Function	Description
CALLOUTCOUNT()	Returns the number of callout shapes that are associated with the shape.
CONTAINERCOUNT()	Returns the number of containers that the shape is a member of.
CONTAINERMEMBERCOUNT()	Returns the number of member shapes in the container shape.
LISTMEMBERCOUNT()	Returns the number of member shapes in the list container shape.

Table 6 shows additional ShapeSheet functions.

Table 6. Additional ShapeSheet functions

Function	Description
HASCATEGORY(string)	Returns TRUE if the specified string is found in the shape's categories list.
LISTORDER()	Returns the one-based order for the shape within a list.

Figure 20 shows a rectangular process shape that belongs to a container. The figure shows the total number of shapes in the container by using a text field that contains the formula CONTAINERSHEETREF(Index, Category):

CONTAINERSHEETREF(1)!CONTAINERMEMBERCOUNT()

Figure 20. Number of shapes in the container

The Index parameter for the CONTAINERSHEETREF function tells Visio to return the topmost container in the case where a shape belongs to multiple containers. If multiple-container membership is common, designers can also provide a Category parameter to ensure that only containers of a specific type are considered.

Persisting Structured-Diagram Relationships

This section is provided for reference only. The relationships among containers, lists, callouts, and shapes are stored in a ShapeSheet cell named Relationships. This cell uses a series of DEPENDSON functions, one for each different type of relationship that the object has. Note that changes to this cell will not trigger actual relationship changes; Visio uses this only as a means to store the relationship information. This cell is not intended to be modified by end users or shape designers.

Table 7 shows the types of relationships.

Table 7. Structured-diagram relationships

Value	Description
1	Shapes that are members of this container.
2	Shapes that are members of this list.
3	Callouts that are associated with this shape.
4	Containers that this shape is a member of.
5	The list that this list item is a member of.
6	The shape associated with this callout.
7	The container on whose left boundary this shape sits
8	The container on whose right boundary this shape sits.
9	The container on whose top boundary this shape sits.
10	The container on whose bottom boundary this shape sits.
11	The list that this list overlaps.

For example, a shape named Process that is a member of a container named Container 1 would have the following Relationships cell formula: =SUM(DEPENDSON(4,Container 1!SheetRef())). The container’s Relationships cell would have the following formula: =SUM(DEPENDSON(1,Process!SheetRef())).

If the Process shape were on the boundary of the left edge of the container, its Relationships cell would have the following formula: =SUM(DEPENDSON(7,Container 1!SheetRef()),DEPENDSON(4,Container 1!SheetRef())). The container’s cell would remain as previously listed.

A shape that is a member of two containers would have the following formula: =SUM(DEPENDSON(7),DEPENDSON(4,Container 1!SheetRef(),Container 2!SheetRef())), and so forth.

Using Automation with Structured-Diagram Shapes

This section describes the programmability features for containers, lists, and callouts in Visio 2010. The part of the Visio API that manages these structured-diagram shapes is known as the structured-diagram API. This API enables developers to identify the logical relationships between shapes, add or change the relationships between shapes, and detect when the user makes changes to the relationships between shapes.

Structured-Diagram API Overview

Figure 21 shows the key objects, properties, and methods in the structured-diagram API:

Figure 21. Structured-diagram API

There are two new objects in the API. ContainerProperties is an extension of the Shape object. It encapsulates the special properties and behaviors of containers and lists. RelatedShapePairEvent is an object used with the structured-diagram API events, where Visio can describe a relationship being formed or broken between two shapes. The remaining parts of the API are additions to existing Visio objects.

Enabling Structured-Diagram Behaviors in Solutions

Visio 2010 introduces a new feature called diagram services that manages what diagramming behaviors are enabled in the document. There are diagram services that control the behavior of the Auto Size Page feature and diagram services that control the behaviors of containers, lists, and callouts. These services are turned on and off at the document level. When a service is off, changes made in the diagram by using automation will not trigger the diagramming behaviors related to that service. (Changes made in the user interface are not subject to the diagram service state.)

For example, the Auto Size Page feature normally increases the page size if a shape is placed outside the page boundary. However, when a shape is placed outside the page by means of automation, the Auto Size Page feature responds only if the Auto Size Page diagram service is enabled. Similarly, dropping a shape on top of a container normally makes it a member of the container and causes the container to resize to fit it. However, when the shape is dropped by using automation, the containers feature responds only if the structured-diagram service is enabled.

The reason Visio 2010 includes this capability is that solution developers may not always want these diagramming behaviors to be triggered while they are manipulating shapes in the diagram. This may be true especially for existing solutions that did not incorporate the new Visio 2010 behaviors and were designed for shapes to respond in ways consistent with Visio 2007. For existing solutions to work as originally designed, all diagram services in Visio 2010 are disabled by default. Solution developers must opt the document in to the new diagramming behaviors.

You can check or change diagram service states by using the Document.DiagramServicesEnabled property. The value of this property is a mask of all the services that are currently enabled. Available services and values, as defined by the VisDiagramServices enumeration, are listed in Table 8. It is possible for a solution to opt into just one service, all the services supported in Visio 2010, or even all existing and future services.

Table 8. VisDiagramServices constants

Constant	Value	Description
visServiceAll	-1	All diagram services.
visServiceVersion140	7	Diagram services that exist in Visio 2010.
visServiceNone	0	No diagram services (default).
visServiceAutoSizePage	1	AutoSize page behaviors.
visServiceStructureBasic	2	Behaviors that maintain existing structured-diagram relationships but do not create new relationships.
visServiceStructureFull	4	Structured-diagram behaviors that match the behaviors in the user interface.

There are two services for structured-diagram behaviors. The StructureBasic service maintains relationships but does not form new ones. This might be appropriate for solution developers who want to respect the user’s usage of containers, lists, and callouts but do not want the solution itself to inadvertently form relationships when shapes are moved around the page. The StructureFull service maintains relationships and can form new relationships, as well. This matches the behaviors that are triggered in the user interface. If both services are enabled, Visio uses the StructureFull set of behaviors.

Disabling Structured-Diagram Behaviors in Solutions

As discussed in the previous section, structured-diagram behaviors triggered by using automation are disabled by default and must be enabled for solutions that use the diagram services feature. Structured-diagram behaviors triggered in the user interface are enabled by default and are not subject to the diagram services state.

It is possible to disable structured-diagram behaviors altogether in the UI and API. Solution developers can add a cell named User.msvSDStructureDisabled to the Pagesheet of a Page and set the value to TRUE.

Common Tasks That Use the Structured-Diagram API

The following typical structured-diagram tasks show the API in more detail. For a complete list of the special flags that can be passed into the methods, look at the Object Browser within the Visual Basic Editor in Visio.

Add a Container to the Page

You can add containers to a page by calling the traditional Page.Drop method, which adds the shape at the coordinates specified without affecting the membership of existing shapes on the page. However, there is a new Page.DropContainer method (shown in the following code), which not only drops the container but also sizes it around a set of shapes and makes those shapes members of the container. This is the behavior in the UI when a shape or shapes are selected and a user clicks Container on the Insert tab. DropContainer needs an object for the container shape. To use one of the shapes in the Insert Container gallery, use the GetBuiltInStencilFile method to retrieve the hidden stencil where these containers are stored.

Dim vsoDoc1 As Visio.Document
Set vsoDoc1 = Application.Documents.OpenEx(Application.GetBuiltInStencilFile(visBuiltInStencilContainers, visMSUS), visOpenHidden)
Application.ActivePage.DropContainer vsoDoc1.Masters.ItemU("Container 1"), Application.ActiveWindow.Selection
vsoDoc1.Close

Add a Shape to a Container

You add shapes to a container by moving or dropping them onto the container, using existing Visio API properties and methods (if the StructureFull diagram service is enabled). You can explicitly add shapes to a container by using the AddMember method, shown in the following code. This is useful when the shape already overlaps the container and is not yet a member. It is also helpful if developers want to force the container to expand to encompass the new member.

vsoContainerShape.ContainerProperties.AddMember vsoShape, visMemberAddExpandContainer

Find the Containers on a Page

To discover what containers exist in a document, Visio provides a direct way to get the set of containers in a selection or on a page. The GetContainers method, shown in the following code, returns an array of shape IDs for the containers. Containers that are nested within other containers can be included or excluded by using flags.

For Each containerID In vsoPage.GetContainers(visContainerIncludeNested)
    Set vsoContainerShape = vsoPage.Shapes.ItemFromID(containerID)
    ' Insert additional code here.
Next

Get the Shapes in a Container

Solutions can identify the members of a container by using the GetMemberShapes method (shown in the following code), which returns an array of shape IDs for the member shapes. The flags allow certain kinds of member shapes to be filtered out of the returned array.

For Each memberID In vsoContainerShape.ContainerProperties.GetMemberShapes(visContainerFlagsDefault) 
    Set vsoShape = vsoPage.Shapes.ItemFromID(memberID) 
    ' Insert additional code here. 
Next

Add a New Shape to a List

Although shapes can be dropped on the page and then placed into lists, there is a new Page.DropIntoList method (shown in the following code), which performs both tasks together.

Application.ActivePage.DropIntoList vsoMaster, vsoListShape, 1

Reorder a List

Every member of a list is placed in a specific position, and you can return the ordinal value by using the ContainerProperties.GetListMemberPosition method. To reorder a member, you can call the ContainerProperties.ReorderListMember method, shown in the following code. Both methods use 1 to indicate the first position in the list.

vsoListShape.ContainerProperties.ReorderListMember vsoShape, 2

Add a Callout to the Page

You can add callouts to a page by calling the traditional Page.Drop method, which adds the shape at the specified coordinates. However, there is a new Page.DropCallout method (shown in the following code), which not only drops the callout but also associates it with a target shape and positions it near the target shape. This is the behavior in the UI when a shape or shapes are selected and the user clicks Callout on the Insert tab. As with DropContainer, DropCallout needs an object for the callout shape. To use one of the shapes in the Insert Callout gallery, use the GetBuiltInStencilFile method to retrieve the hidden stencil where these containers are stored.

Dim vsoDoc1 As Visio.Document
Set vsoDoc1 = Application.Documents.OpenEx(Application.GetBuiltInStencilFile(visBuiltInStencilCallouts, visMSUS), visOpenHidden) 
Application.ActivePage.DropCallout vsoDoc1.Masters.ItemU("Text callout"), vsoTargetShape
vsoDoc1.Close

Get the Target Shape for a Callout

A shape can have multiple callouts, but a callout can have only one target shape at a time. The Shape.CalloutsAssociated property returns an array of callout shape IDs. Get or set the target shape of a callout by using the Shape.CalloutTarget property, shown in the following code.

Set vsoShape = vsoCalloutShape.CalloutTarget

Structured Diagrams Events

In addition to manipulating the containers, lists, and callouts in a document, developers can also respond to user actions that relate to these shapes. Containers, lists, and callouts work by establishing relationships with other shapes. Visio raises an event whenever one of these relationships is formed or broken. For example, adding a shape to a container forms a new relationship between the shape and the container.

When a relationship event is raised, Visio specifies the details in a RelatedShapePairEvent object. The FromShapeID property of this object indicates the container, list, or callout involved in the relationship. The ToShapeID property indicates the other shape involved in the relationship. Thus when you add a shape to a container, the ToShapeID refers to the new member shape. When you associate a callout with a target shape, the ToShapeID refers to the target shape.

The following events are available for Application, Documents, Pages, and Page event lists (and Document event lists when you use the AddAdvise method):

• ContainerRelationshipAdded

• ContainerRelationshipDeleted

• CalloutRelationshipAdded

• CalloutRelationshipDeleted

Also, the ShapeChanged event will now occur when members of a list shape are reordered. The event passes the list shape as an argument and includes the string "/ListReorder" in the EventInfo argument.

Conclusion

Visio 2010 allows users to organize information quickly and easily by means of a rich set of structured-diagram capabilities. Structured diagrams allow users to capture and maintain the logical relationships in a diagram, and Visio uses this information to provide streamlined behaviors for users.

Visio offers features such as containers, lists, and callouts to manage the logical relationships between shapes. Shape designers and developers can extend the capabilities of structured diagrams by means of custom shapes and solutions. In total, structured diagrams represent a significant new opportunity for users to manage increasing diagram complexity.

Additional Resources

Visio Developer Center