{"id":1620,"date":"2018-08-24T07:51:42","date_gmt":"2018-08-24T14:51:42","guid":{"rendered":"https:\/\/developer.microsoft.com\/en-us\/office\/blogs\/?p=1620"},"modified":"2021-10-18T11:27:33","modified_gmt":"2021-10-18T18:27:33","slug":"container-list-and-callout-api-in-visio-2010","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/container-list-and-callout-api-in-visio-2010\/","title":{"rendered":"Container, List and Callout API in Visio 2010"},"content":{"rendered":"

This post examines the programmability features for Containers<\/a>, Lists and Callouts<\/a> in Visio 2010.\u00a0 It supplements an earlier post<\/a> that describes how these special shapes are constructed and how they can be customized.\u00a0 Collectively these shapes are known as Structured Diagram elements, and the part of the Visio API that manages these elements is known as the Structured Diagram API.\u00a0 This API enables developers to use Structured Diagram elements in their solutions.\u00a0 Developers can identify the relationships between these elements and other shapes, they can add or change the relationships with other shapes, and they can detect when the user makes changes to the relationships with other shapes.<\/p>\n

 <\/p>\n

Structured Diagram API Overview<\/h2>\n

Here are the key objects, properties and methods in the Structured Diagrams API:<\/p>\n

\"image\"<\/a><\/p>\n

There are two new objects in the API.\u00a0 ContainerProperties<\/strong> is an extension of the Shape object.\u00a0 It encapsulates the special properties and behaviors of containers and lists.\u00a0 RelatedShapePairEvent<\/strong> is an object used with the Structured Diagram API events, where Visio can describe a relationship being formed or broken between two shapes.\u00a0 The remaining parts of the API are additions to existing Visio objects.<\/p>\n

Note that lists are just another type of container as far as the API is concerned.\u00a0 Therefore, lists use all the same objects, properties and methods as containers; and lists have a few additional properties and methods as well (those with \u201cList\u201d in their name).<\/p>\n

 <\/p>\n

Enabling Structured Diagram Behaviors in Solutions<\/h2>\n

Visio 2010 introduces a new feature called Diagram Services that manages what diagramming behaviors are enabled in the document.\u00a0 There are diagram services that control the behavior of Auto Size Page<\/a> and diagram services that control the behaviors of Containers, Lists and Callouts.\u00a0 These services are turned on and off at the document level.\u00a0 When a service is off, changes made in the diagram through automation will not trigger the diagramming behaviors related to that service.\u00a0 (Changes made through the user interface are not subject to the diagram service state.)<\/p>\n

For example, the Auto Size Page feature will normally grow the page size if a shape is placed outside the page boundary.\u00a0 However, when a shape is placed outside the page via automation, the Auto Size Page feature will only respond if the Auto Size Page diagram service is enabled.\u00a0 Similarly, dropping a shape on top of a container will normally make it a member of the container and cause the container to resize to fit it.\u00a0 However, when the shape is dropped via automation, the Containers feature will only respond if the Structured Diagram service is enabled.<\/p>\n

The reason Visio 2010 includes this capability is that solutions may not always want these diagramming behaviors to get triggered while they are manipulating shapes in the diagram.\u00a0 This may especially be true for existing solutions that have no knowledge of the new Visio 2010 behaviors and have expectations that shapes respond in ways consistent with Visio 2007.\u00a0 In order for existing solutions to work as originally designed, all diagram services in Visio 2010 are disabled by default.\u00a0 Solutions must opt the document in to the new diagramming behaviors.<\/strong>\u00a0 Note that diagram service states apply to automation properties and methods that existed in Visio 2007.\u00a0 When a new Visio 2010 automation method is explicitly invoked by a solution – such as any of the examples below \u2013 the service state is ignored.\u00a0 The presumption is that the solution wants the Visio 2010 behavior associated with that method.<\/p>\n

Diagram service states are checked or changed using the Document<\/strong>.DiagramServicesEnabled<\/strong> property.\u00a0 The value of this property is a mask of all the services currently enabled.\u00a0 Available services and values are listed in the table below.\u00a0 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.<\/p>\n

VisDiagramServices<\/strong> values:<\/p>\n\n\n\n\n\n\n\n\n\n
Enum<\/strong><\/td>\nValue<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
visServiceAll<\/td>\n-1<\/td>\nAll diagram services<\/td>\n<\/tr>\n
visServiceVersion140<\/td>\n7<\/td>\nDiagram services that exist in Visio 2010<\/td>\n<\/tr>\n
visServiceNone<\/td>\n0<\/td>\nNo diagram services (default)<\/td>\n<\/tr>\n
visServiceAutoSizePage<\/td>\n1<\/td>\nAutoSize page behaviors<\/td>\n<\/tr>\n
visServiceStructureBasic<\/td>\n2<\/td>\nBehaviors that maintain existing Structured Diagram relationships but do not create new relationships<\/td>\n<\/tr>\n
visServiceStructureFull<\/td>\n4<\/td>\nStructured Diagram behaviors that match the behaviors in the user interface<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

There are two services for Structured Diagram behaviors.\u00a0 The StructureBasic service maintains relationships but will not form new ones.\u00a0 This might be appropriate for a solution that wants to respect the user\u2019s usage of Containers, Lists and Callouts but does not want the solution itself to inadvertently form relationships when shapes are moved around the page.\u00a0 The StructureFull service maintains relationships and will form new relationships as well.\u00a0 This matches the behaviors that are triggered in the user interface.\u00a0 If both services are enabled, then Visio uses the StructureFull set of behaviors.<\/p>\n

 <\/p>\n

Common Tasks with the Structured Diagram API<\/h2>\n

Let\u2019s look at some typical Structured Diagram tasks to explore the API in greater detail.\u00a0 For a complete list of the special flags that can be passed into the methods, look at the Object Browser within the VBA editor in Visio.<\/p>\n

Add a container to the page<\/h2>\n

Containers can be added to a page by calling the traditional Page.Drop method, which will add the shape at coordinates you specify without affecting the membership of existing shapes on the page.\u00a0 However, there is a new Page method \u2013 Page.DropContainer<\/strong> – that will not only drop the container but will also size it around a set of shapes and make those shapes members of the container.\u00a0 This is the behavior in the UI when using Insert > Container when a selection exists.\u00a0 DropContainer needs an object for the container shape.\u00a0 If you want to use one of the shapes in the Insert Container gallery, you can use the GetBuiltInStencilFile<\/strong> method to retrieve the hidden stencil where these containers are stored.<\/p>\n

Dim vsoDoc1 As Visio.Document\nSet vsoDoc1 = Application.Documents.OpenEx(Application.GetBuiltInStencilFile<\/strong>(visBuiltInStencilContainers, visMSUS), visOpenHidden)\nApplication.ActivePage.DropContainer<\/strong> vsoDoc1.Masters.ItemU(“Container 1”), Application.ActiveWindow.Selection\nvsoDoc1.Close<\/p><\/blockquote>\n

Add a shape to a container<\/h2>\n

Shapes are added to a container by moving or dropping them onto the container (if the StructureFull diagram service is enabled).\u00a0 Shapes can be explicitly added to a container using the AddMember<\/strong> method.\u00a0 This is useful when the shape already overlaps the container and is not yet a member.\u00a0 It is also helpful if you want to force the container to expand to encompass the new member.<\/p>\n

vsoContainerShape.ContainerProperties<\/strong>.AddMember<\/strong> vsoShape, visMemberAddExpandContainer<\/p><\/blockquote>\n

Find the containers on a page<\/h2>\n

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.\u00a0 The GetContainers<\/strong> method returns an array of Shape IDs for the containers.\u00a0 Containers nested within other containers can be included or excluded using flags.<\/p>\n

For Each containerID In vsoPage.GetContainers<\/strong>(visContainerIncludeNested)\nSet vsoContainerShape = vsoPage.Shapes.ItemFromID(containerID)\n‘…\nNext<\/p><\/blockquote>\n

Get the shapes in a container<\/h2>\n

Solutions can identify the members of a container using the GetMemberShapes<\/strong> method, which returns an array of Shape IDs for the member shapes.\u00a0 The flags allow certain kinds of member shapes to be filtered out of the array returned.<\/p>\n

For Each memberID In vsoContainerShape.ContainerProperties<\/strong>.GetMemberShapes<\/strong>(visContainerFlagsDefault)\nSet vsoShape = vsoPage.Shapes.ItemFromID(memberID)\n‘…\nNext<\/p><\/blockquote>\n

Reorder a list<\/h2>\n

Every member of a list is placed in a specific position, and that ordinal value can be retrieved with the ContainerProperties<\/strong>.GetListMemberPosition<\/strong> method.\u00a0 To reorder a member, you can call the ContainerProperties<\/strong>.ReorderListMember<\/strong> method.\u00a0 Both methods use 1 to indicate the first position in the list.<\/p>\n

vsoListShape.ContainerProperties<\/strong>.ReorderListMember<\/strong> vsoShape, 2<\/p><\/blockquote>\n

Add a callout to the page<\/h2>\n

Callouts can be added to a page by calling the traditional Page.Drop method, which will add the shape at coordinates you specify.\u00a0 However, there is a new Page method \u2013 Page.DropCallout <\/strong>– that will not only drop the callout but will associate it with a target shape and position it near the target shape.\u00a0 This is the behavior in the UI when using Insert > Callout when a selection exists.\u00a0 As with DropContainer, DropCallout needs an object for the callout shape.\u00a0 If you want to use one of the shapes in the Insert Callout gallery, you can use the GetBuiltInStencilFile<\/strong> method to retrieve the hidden stencil where these containers are stored.<\/p>\n

Dim vsoDoc1 As Visio.Document\nSet vsoDoc1 = Application.Documents.OpenEx(Application.GetBuiltInStencilFile<\/strong>(visBuiltInStencilCallouts, visMSUS), visOpenHidden)\nApplication.ActivePage.DropCallout<\/strong> vsoDoc1.Masters.ItemU(“Callout 1”), vsoTargetShape\nvsoDoc1.Close<\/p><\/blockquote>\n

Get the target shape for a callout<\/h2>\n

A shape can have multiple callouts, but a callout can have only one target shape at a time.\u00a0 The Shape<\/strong>.CalloutsAssociated<\/strong> property returns an array of callout shape IDs.\u00a0 You can get or set the target shape of a callout using the Shape<\/strong>.CalloutTarget<\/strong> property.<\/p>\n

Set vsoShape = vsoCalloutShape.CalloutTarget<\/strong><\/p>\n

 <\/p><\/blockquote>\n

Structured Diagram Events<\/h2>\n

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

When a relationship event fires, Visio specifies the details in a RelatedShapePairEvent object.\u00a0 The FromShapeID<\/strong> property of this object indicates the container, list or callout involved in the relationship.\u00a0 The ToShapeID<\/strong> property indicates the other shape involved in the relationship.\u00a0 Thus when adding a shape to a container, the ToShapeID would refer to the new member shape, and when associating a callout with a target shape, the ToShapeID would refer to the target shape.<\/p>\n

The following events are available for Application, Documents, Pages and Page event lists:<\/p>\n

ContainerRelationshipAdded<\/strong><\/p>\n

ContainerRelationshipDeleted<\/strong><\/p>\n

CalloutRelationshipAdded<\/strong><\/p>\n

CalloutRelationshipDeleted<\/strong><\/p><\/blockquote>\n

Also the ShapeChanged event will now fire when members of a list shape are reordered.\u00a0 The event passes the list shape as an argument and includes the string \u201c\/ListReorder\u201d in the EventInfo argument.<\/p>\n

 <\/p>\n

Feedback<\/h2>\n

The Structured Diagrams feature set \u2013 Containers, Lists and Callouts \u2013 offers both end users and developers significant new diagramming capabilities in Visio 2010.\u00a0 We\u2019re interested to hear what developers think of this API functionality, so please use the Send a Smile feedback tool<\/a> or leave a comment below.<\/p>\n","protected":false},"excerpt":{"rendered":"

This post examines the programmability features for Containers, Lists and Callouts in Visio 2010.\u00a0 It supplements an earlier post that describes how these special shapes are constructed and how they can be customized.<\/p>\n","protected":false},"author":69200,"featured_media":25159,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[77],"class_list":["post-1620","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-365-developer","tag-visio"],"acf":[],"blog_post_summary":"

This post examines the programmability features for Containers, Lists and Callouts in Visio 2010.\u00a0 It supplements an earlier post that describes how these special shapes are constructed and how they can be customized.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/1620","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69200"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=1620"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/1620\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=1620"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=1620"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=1620"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}