Inserting a Legend in Data-Connected Diagrams Programmatically in Visio 2010

  • Article

Office Visual How To

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: Office 2010 | VBA | Visio 2010 | Visual Studio

Published:  May 2011

Provided by:  Eric Schmidt, Microsoft Corporation

Overview

This Visual How To explains how to insert programmatically a legend into a data-connected diagram by using the following steps:

  1. Setting the Document.DiagramServicesEnabled property to enable the services that aggregate the new structured-diagram and AutoSize behaviors in Microsoft Visio 2010.

  2. Using the Documents.OpenEx method to open a built-in stencil in Visio 2010.

  3. Using the Page.DropLegend method to add a legend to a diagram page that contains Data Graphics.

  4. Using the Selection.Move method to move the legend on the page after it has been inserted.

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.

Note

Data Graphics and data legends are available only in Visio Premium 2010 and Visio Professional 2010.

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.)

Important

You should reset the Document.DiagramServicesEnabled property to its original value after you have run the rest of your code. This enables other solutions that do not use diagram services to function correctly.

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.

Note

The file name of the built-in legend stencil is LEGEND_U.vss. It is not exposed within the Visio 2010 UI.

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.

Code It

This section describes how to add a legend to a Visio 2010 diagram that contains Data Graphics by using the following general steps:

  1. Creating a C# Visio 2010 add-in project in Microsoft Visual Studio 2010.

  2. Adding the sample code to the solution.

  3. Testing the solution.

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

  1. On the File menu in Visual Studio 2010, point to New, and then click Project.

  2. In the Installed Templates list, expand the Visual C# node, and then expand the Office node.

  3. Click 2010, and then select Visio 2010 Add-in.

  4. Name the project, and either accept the default location or browse to another location in which to save the project.

  5. Click OK.

  6. Save the project.

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

  1. The following example uses the Path.Combine() method to get the file path of the Visio document being opened. To use the System.IO.Path.Combine method, you have to add the following code to the using directives at the top of the Visual Studio 2010 project.

    using System.IO;

  2. In the ThisAddIn_Startup method of the Visual Studio 2010 project, paste the following code. If you are not using the sample diagram file from Office.com, replace the folder and name of the sample file with the file that you want to open.

    Microsoft.Office.Interop.Visio.Document visDoc;
Microsoft.Office.Interop.Visio.Page dataGraphicPage;
Microsoft.Office.Interop.Visio.Document visLegendStencil;

// Open the sample file and page.
string docPath = 
    Path.Combine(System.Environment.GetFolderPath(System.Environment.SpecialFolder.MyDocuments),
    "test\\CallCenterPerformance.vsd");
visDoc = this.Application.Documents.Open(docPath);
dataGraphicPage = Application.ActivePage;

// Save the current diagram services setting.
// and change the setting to enable structured diagram behaviors.
int visServices = visDoc.DiagramServicesEnabled;
visDoc.DiagramServicesEnabled = (int)Visio.VisDiagramServices.visServiceVersion140;

// Get the name of the built-in Visio stencil that contains the legend master shapes.
string visLegendStencilName = Application.GetBuiltInStencilFile(Visio.VisBuiltInStencilTypes.visBuiltInStencilLegends,
    Visio.VisMeasurementSystem.visMSUS);

// Open the legend stencil.
visLegendStencil = Application.Documents.OpenEx(visLegendStencilName, 
    (short)Visio.VisOpenSaveArgs.visOpenHidden);

// Drop the legend onto the page that contains the Data Graphics.
Visio.Shape visLegend = 
    dataGraphicPage.DropLegend(visLegendStencil.Masters.get_ItemU("Outer list"),
    visLegendStencil.Masters.get_ItemU("Field container"), 
    Visio.VisLegendFlags.visLegendPopulate);

// Close the built-in legend stencil.
visLegendStencil.Close();

// Move the legend to the lower-left corner of a drawing in landscape orientation.
this.Application.ActiveWindow.Select(visLegend, (short)Visio.VisSelectArgs.visSelect);
this.Application.ActiveWindow.Selection.Move(-7.75, -6.5);

// Reset the diagram services to the original setting.
visDoc.DiagramServicesEnabled = visServices;

  3. Save the project.

Now, test the solution that you created in Visual Studio 2010.

To test the solution

  1. On the Debug menu in Visual Studio 2010, click Start Debugging.

  2. Switch to Visio 2010.

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.

 See It

Watch the video

> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/1541d0e3-2d56-4c0b-8e22-1c822e8b65dc]

Length: 8:03

Explore It