Inserting a Legend in Data-Connected Diagrams Programmatically in Visio 2010
Summary: Learn how to insert a legend into a data-connected diagram programmatically in Microsoft Visio 2010 by using the Document.DiagramServicesEnabled property, Page.DropLegend method, and Documents.OpenEx method.
Applies to: Microsoft Visio Premium 2010 | Microsoft Visio Professional 2010 | Microsoft Visual Studio 2010
Published: May 2011
Provided by: Eric Schmidt, Microsoft Corporation
This Visual How To explains how to insert programmatically a legend into a data-connected diagram by using the following steps:
For Visio 2010 pages that contain data-connected diagrams, you can add a legend that displays active data graphic icons and the fields that they represent. You can apply a legend to a drawing through the user interface (UI) by clicking Insert Legend in the Display Data group on the Data tab. However, you can also apply a legend to a drawing page programmatically.
To add a legend programmatically, you first have to set the Document.DiagramServicesEnabled property to a value that enables structured diagram behaviors. This is necessary because the legend is composed of a container shape that holds other shapes, and Document.DiagramServicesEnabled enables you to interact programmatically with the legend as a single shape. The code example in this Visual How To saves the current value of the Document.DiagramServicesEnabled property of the drawing and then sets the property to an integer that corresponds to the visServiceVersion140 constant of the VisDiagramServices enumeration. visServiceVersion140 enables all diagram services that exist in Visio 2010. (By default, the Document.DiagramServicesEnabled property of a Visio 2010 drawing is set to visServiceNone, meaning that no diagram services are enabled.)
Next, to access the legend shapes, you have to open a built-in Visio 2010 stencil that contains the master shapes that create the legend. To do that, get the file name of the stencil by using the Application.GetBuiltInStencilFile method, specifying the visBuiltInStencilLegends constant of the VisBuiltInStencilTypes enumeration for the StencilType parameter. Then pass the stencil file name as an argument to the Documents.OpenEx method. The code example in this Visual How To also uses the visOpenHidden constant (as a 16-bit signed integer) of the VisOpenSaveArgs enumeration for the Flags parameter of the Documents.OpenEx method. This returns the stencil as a hidden document, which keeps the user from seeing the stencil open and close. However, this step is not required to add a legend to a drawing.
Once the legend stencil is open, you can use the Page.DropLegend method to drop the legend shape onto the drawing page. The Page.DropLegend method has three required parameters: OuterList, InnerContainer, and populateFlags. Both the OuterList and InnerContainer parameters can take either a Master or MasterShortcut object. The populateFlags parameter must be a constant from the VisLegendFlags enumeration. The Page.DropLegend method returns the legend as a container shape.
This Visual How To uses a minimal C# Visio 2010 add-in project in to show how to add a legend to a drawing page. For more information about how to manipulate data graphics programmatically, see the article About Displaying Data Graphically.
This section describes how to add a legend to a Visio 2010 diagram that contains Data Graphics by using the following general steps:
Inserting a Data Graphic Legend by Using a C# Visio Add-In
Use the following procedures to create and test a minimal Visio 2010 add-in in Visual Studio 2010 that adds a legend to a file that has Data Graphics. To better demonstrate the code, create a data-connected diagram and apply Data Graphics to some of the shapes. (You can also download the sample diagram file that is used in the accompanying video from Office.com.)
To create a Visio 2010 C# add-in project in Visual Studio 2010
Now, use the following procedure to add the sample code that opens a Visio 2010 file that includes Data Graphics, and then drops the legend onto the active page.
To add the sample code to the solution
Now, test the solution that you created in Visual Studio 2010.
To test the solution
The add-in runs and opens the file that you specified. After the file has opened, a legend appears in the upper-right corner of the drawing, displaying an icon for each data graphic that appears on the active page.
Watch the video