Building Custom Data Graphics for Visio 2007

Mark Nelson, Microsoft Corporation

September 2006

Applies to: Microsoft Office Visio Professional 2007

Summary: Learn how to extend the Data Graphics feature in Microsoft Office Visio Professional 2007 by creating custom data graphics and by creating custom graphical content for use in data graphics. (13 printed pages)

Contents

  • Introduction to Data Graphics

  • Overview of Data Graphics

  • Using Data Graphics in Drawings

  • Creating Custom Data Graphics

  • Creating Additional Callouts

  • Custom Text Callouts and Data Bars

  • Custom Icon-Set Callouts

  • Best Practices for Constructing Callout Shapes

  • Hidden Masters and Removing Hidden Information

  • Examining Built-in Callout Shapes in Visio

  • Conclusion

  • Additional Resources

Introduction to Data Graphics

Microsoft Office Visio 2007 Professional offers new ways for businesses to visualize information. New data connectivity, data linking, and data refresh features enable users to more easily connect to external data and associate it with specific shapes in a drawing, and to more easily refresh the data manually or automatically. The Data Graphics feature presents linked data and other shape information graphically in a diagram. Together, these capabilities make it faster and easier to communicate important information for making decisions and taking actions.

You can use data graphics to present information associated with shapes in a concise, understandable format. Text, geometry, formatting, and graphics are combined to help users identify issues, illustrate patterns in data, and communicate status. Data graphics include several customization options that provide users with the widest variety of visualizations possible. This article summarizes the full range of options, from reusing existing data graphics to creating completely new visualizations for information.

Figure 1. Network diagram with data graphics

Network diagram with data graphics

Overview of Data Graphics

A data graphic is a collection of data presented in a diagram either as a set of graphical widgets or by formatting shapes that contain data. The widgets are known as callouts. These callouts are placed on or next to a shape that contains data, referred to as the target shape in this document. The data displayed is typically Shape Data (formerly known as Custom Properties), but other shape information and custom expressions can also be displayed.

Visio provides three types of callouts, as listed in Table 1.

Table 1. Data Graphics callout types

Type

Description

Text callouts

Display data as text.

Data-bar callouts

Display data by modifying some visual aspect of the callout, such as the amount filled in a progress bar.

Icon-set callouts

Display data by using icons that appear or disappear based on conditional statements.

A fourth way of displaying data in a shape is by using Color by Value. This method applies conditional formatting to the shape itself rather than displaying information in a callout.

Figure 2. Sample data graphic illustrating callout types

Sample data graphic illustrating callout types

A data graphic consists of the set of callouts and Color by Value rules used to display data on a shape. Each shape can have only one data graphic applied at a time, but a data graphic can consist of many callouts and Color by Value rules. You apply data graphics in the Data Graphics task pane. To display this task pane, on the Data menu, click Display Data on Shapes. You can also define and modify data graphics by right-clicking a shape, pointing to Data, and then clicking Edit Data Graphic.

On the drawing page, a data graphic is a set of special shapes added to a target shape that contains the data to be displayed. When you apply a data graphic, the target shape becomes a group (if it is not already a group) and the data graphic shapes are added as subshapes of that group. Data graphic shapes usually appear on top of any existing subshapes that are included in target shapes.

Using Data Graphics in Drawings

You apply a data graphic to shapes in a drawing by selecting the shapes and then clicking the data graphic that you want to apply in the Data Graphics task pane. After you use a data graphic in a document, you can reuse it in other documents.

To copy a data graphic from one document to another, apply the data graphic to a shape in the current drawing. Then copy the shape and paste it into the other document. This action copies the data graphic definition to the other document, and it copies the callouts used by the data graphic. You can then delete the shape from the first document, but the data graphic remains available in the second document.

It is not possible to define a data graphic in a central location for use in all documents, but you can build a data graphic into a Visio template. By doing so, you make the data graphic available in all drawings created from that template. To create a template that contains a data graphic, copy the data graphic into a blank drawing template or into an existing template, by using the method described previously. Then save the document as a Visio template.

One additional option is to pre-associate a data graphic with a master shape. This method is useful for diagrams in which data graphics are an integral part of the drawing and in which each shape can use the same data graphic to display information. To build a data graphic into a master shape, apply the data graphic to a shape on the page and then drag the shape to a stencil to create a master. Note that, by doing this, you remove the association that the shape had with its previous master. Visio makes a new master from this union of shape and data graphic. Visio also places a copy of the data graphic and any callout masters in the stencil.

Creating Custom Data Graphics

You can create custom data graphics, or you can start by modifying an existing data graphic. To create a data graphic, open the Data Graphics task pane, then click New Data Graphic to display the New Data Graphic dialog box. You can add callouts and Color by Value rules to the data graphic by clicking New Item.

Figure 3. Data Graphics task pane and New Data Graphic dialog box

Data Graphics task pane, New Data Graphic dialog

To create a data graphic from an existing data graphic, right-click the existing data graphic in the task pane and then click Duplicate. To modify the new data graphic, right-click it and then click Edit Data Graphic to display the Edit Data Graphic dialog box (which is identical to the New Data Graphic dialog box except for its title). You can add, delete, or modify callouts and Color by Value rules in the Edit Data Graphic dialog box.

Visio provides many ways to customize an existing data graphic. In the Edit Data Graphic dialog box, you can modify the default position of callouts or the stacking order of callouts. Text callouts, data bars, icon sets, and color-by-value items each have properties that control their appearance, location, and formatting.

For callout items, you can replace the callout shape itself with a different widget that presents information in a different way. For text callouts and data bars, each callout shape defines a custom set of properties that offer even more control over the appearance of the callout. These options provide a wide variety of ways that you can use built-in Visio components to customize data graphics.

Figure 4. New Text dialog box

New Text dialog box

Creating Additional Callouts

You can also create completely new text callouts, data-bar callouts, and icon-set callouts for use in data graphics. The callouts used in data graphics are just Visio shapes that have extra behaviors added to them. Callout shapes have a signature that enables Visio to identify them as special shapes. Visio expects callouts to follow a few rules to integrate properly with the Data Graphics feature. Creating callouts requires a basic understanding of Visio masters and the Visio ShapeSheet spreadsheet.

For a custom callout shape to work with data graphics, the shape must exist as a master in the current document. Visio adds any callouts it finds in the document to the lists of callouts available in the Text dialog box, the Data Bar dialog box, and the Icon Set dialog box. After you apply callout masters as part of a data graphic, Visio automatically copies them from one document to another when you copy the data graphic from document to document.

The purpose of a callout is to display data. Visio provides the callout shape with the necessary data. The callout shape then determines how that information is presented in the shape. The visualization can take on almost any form that you, the shape designer, can imagine. However, you must categorize the callout shape as one of the three supported types: text, data bar, or icon set. Each type has specific requirements for use with data graphics.

Custom Text Callouts and Data Bars

By convention, you use text callouts to display information in a textual form and data bars to display information in a graphical form. The two callout types use similar mechanisms to integrate with the Data Graphics feature.

Visio recognizes a shape as a data-graphics callout if the topmost shape in the master contains the user-defined cell User.msvCalloutType. You can identify a text callout by setting the value of that cell to "Text Callout" or "Heading" (quotation marks required).

Figure 5. Text callout user-defined cells

Text callout user-defined cells

You can identify data-bar callouts by using the cell value "Data Bar" (quotation marks required).

Figure 6. Data-bar callout user-defined cells

Data-bar callout user-defined cells

Visio places the data to be displayed in a Shape Data row named Prop.msvCalloutField. Design the callout to make use of the information in this row in whatever way it wants. Note that Visio uses Shape Data rows in callouts in highly specialized ways and that these rows are not intended to be used as standard Shape Data properties. For this reason, you should set the Invisible cell value in these Shape Data rows to TRUE to hide these rows from the user.

Figure 7. Text and data-bar callout Shape Data cells

Text and data-bar callout Shape Data cells

Visio puts the following information into cells in the Prop.msvCalloutField row when the callout is used in a data graphic.

Table 2. Prop.msvCalloutField cells written by Visio

Cell

Value

Label

Not set by Data Graphics.

Prompt

Not set by Data Graphics.

Type

Not set by Data Graphics.

Format

If data field is a Shape Data property, Format of Shape Data property.

If data field is not a Shape Data property, not set by Data Graphics.

Value

Reference to data field value.

SortKey

If data field is a Shape Data property, Label of Shape Data property.

If data field is not a Shape Data property, not set by Data Graphics.

Invisible

Not set by Data Graphics, TRUE recommended.

Ask

Not set by Data Graphics.

LangID

If data field is a Shape Data property, LangID of Shape Data property.

If data field is not a Shape Data property, LangID of target shape.

Calendar

If data field is a Shape Data property, Calendar of Shape Data property.

If data field is not a Shape Data property, not set by Data Graphics.

You specify the data field to be shown in the callout when you include the callout in a data graphic. You can define additional properties for text callouts or data bars to expose in the Edit Text dialog box or in the Edit Data Bar dialog box. These properties enable you to configure the callout in special ways.

You define custom callout properties by creating additional Shape Data rows that have names beginning with the prefix Prop.msvCalloutProp.

Figure 8. Custom callout property cells

Custom callout property cells

Visio interprets these cells in the property rows in the following ways.

Table 3. Custom callout property cells read by Visio

Cell

Value

Label

Property label to be displayed in dialog boxes.

Prompt

Control type of property (defined below).

Type

Not used.

Format

For List control types, semicolon-delimited list of choices.

For Field control types, format of data field or empty if field is not a Shape Data property.

For String control types, optional default value for the property.

Invisible

Not used by Data Graphics, TRUE recommended.

Ask

Not used.

Visio puts the following information back into these cells in the property rows.

Table 4. Custom callout property cells written by Visio

Cell

Value

Value

Property value.

SortKey

For Field control types where data field is a Shape Data property, Label of Shape Data property.

LangID

For Field control types where data field is a Shape Data property, LangID of Shape Data property.

For Field control types where data field is not a Shape Data property, LangID of target shape.

For Format control types, LangID of data format picture.

Calendar

For Field control types where data field is a Shape Data property, Calendar of data field.

For Format control types, Calendar of data format picture.

Visio supports a variety of input controls in the Edit Text dialog box and in the Edit Data Bar dialog box. The Prompt cell specifies the control to be displayed. Other cells might be interpreted in different ways, depending on the control type.

Table 5. Custom callout property control types

Control Type

Prompt cell value

Control used in dialog box

String

"String"

Text box

Number

"Number"

Text box requiring numeric input

List

"List"

Drop-down list box with choices supplied by the Format cell

Boolean

"Bool"

Drop-down list box with yes and no choices

Date

"Date"

Text box with date picker

Field

"Field"

Data-field drop-down list box

Data Format

"Format"

Text box with Data Format button

Figure 9. Custom callout property examples

Custom callout property examplesCustom callout property example

Field controls offer the same choice of fields as the data-field drop-down list box, with the addition of a [Not Used] choice. If you select [Not Used], Visio places the formula NA() in the property's Value cell.

Custom Icon-Set Callouts

An icon-set callout is a shape that can display up to five different images, depending on a value provided by the Data Graphics feature. Icon-set callouts are different from text callouts and data-bar callouts because the icon-set callout does not use the data-field value directly. In the Edit Icon Set dialog box, you can define a set of conditional statements for icon-set data that determines which icon should be displayed. From the conditional statements, Visio creates a single ShapeSheet formula that returns a number that corresponds to a particular icon.

Visio recognizes a shape as a data-graphics callout if the topmost shape in the master contains the user-defined cell User.msvCalloutType. Icon-set callouts are identified by using the value "Icon Set" (quotation marks required).

A second user-defined cell named User.msvCalloutIconCount tells Visio how many icons the callout supports. This cell should have an integer value of 1, 2, 3, 4, or 5.

A third user-defined cell named User.msvCalloutIconNumber receives the formula from Visio that determines which icon to display. This formula evaluates to -1 when none of the user's conditional statements are true. Otherwise, the formula evaluates to an integer of 0, 1, 2, 3, or 4.

Figure 10. Icon-set callout user-defined cells

Icon-set callout user-defined cells

By convention, you should hide the callout shape when User.msvCalloutIconNumber is -1, although it would be possible to use this state to display another graphic. To hide a shape completely, you must hide all of its geometry, text, and images.

Using Geometry in Icon Sets

A common way to draw an icon is by using shape geometry. A shape can have multiple geometry sections in it, and you can show or hide each section independently, depending on the value you set in the User.msvCalloutIconNumber cell. Similarly, a shape can be a group containing additional subshapes, and you can show or hide the geometry in those subshapes independently.

Figure 11 provides an example of an icon-set callout that has two geometry sections.

Figure 11. Icon-set callout geometry example

Icon-set callout geometry example

The circle is shown for icon values 0, 2, and 4 (displaying the numbers 1, 3, and 5). The square is shown for icon values 1 and 3 (displaying the numbers 2 and 4). Figure 12 shows a geometry section.

Figure 12. Icon-set callout geometry section

Icon set callout geometry section

The NoShow cell in each geometry section controls the visibility of the section. Table 6 lists the complete formulas for the NoShow cells.

Table 6. Icon-set–callout NoShow formulas

Cell

Formula

Geometry1.NoShow

IF(OR(User.msvCalloutIconNumber=0,User.msvCalloutIconNumber=2,
User.msvCalloutIconNumber=4),FALSE,TRUE)

Geometry2.NoShow

IF(OR(User.msvCalloutIconNumber=1,User.msvCalloutIconNumber=3),FALSE,TRUE)

Note that when User.msvCalloutIconNumber is -1, both formulas evaluate to TRUE and no geometry is shown.

Using Images in Icon Sets

Another way to show an icon is by using a picture image, such as a bitmap or a metafile. In this case, the callout shape must be a group shape that contains the image or images as subshapes. Put the user-defined cells for the icon set into the group shape. You can show or hide the images by specifying the value in the group's User.msvCalloutIconNumber cell.

When working with images, it is easier if all the pictures are the same size. Also, the images should be combined into an image strip—a single picture that contains the images arranged in an evenly spaced row. You can perform these manipulations either in Visio or in another graphics editor, such as Paint.

Figure 13 shows an example of an icon set based on images.

Figure 13. Icon-set callout image example

Icon-set callout image example

To create this icon set, draw a rectangle to the final callout size you want. Convert the rectangle to a group and add the required user-defined cells for the icon set. Then add the image strip to the page, and lock its aspect ratio. Resize the image strip until it is exactly 5 times the width of the rectangle (or a different multiple if there are fewer icons in the set).

Figure 14. Icon-set callout image example: Step 1

Icon-set callout image example: Step 1

Using the Crop tool, crop the image strip down to the width of the rectangle. Align the image strip on top of the rectangle and add it to its group. You can delete or permanently hide the rectangle's geometry section.

Figure 15. Icon-set callout image example: Step 2

Icon-set callout image example: Step 2

The final step is to tie the image strip to the group's icon number. In the ShapeSheet of the image strip, the Foreign Image Info section controls the size and position of the picture. Only a portion of the picture is visible in the shape, and the rest is cropped out of view. The ImgOffsetX cell controls what portion of the image is seen. This cell moves the image based on the icon value of the group.

Figure 16. Icon-set callout Foreign Image Info section

Icon-set callout Foreign Image Info section

Best Practices for Constructing Callout Shapes

Using the following design practices can help you create professional-looking callout shapes.

Master Name

For text callouts and data bars, the name assigned to the callout master is the name displayed in the Callout drop-down list in the Edit Text dialog box and in the Edit Data Bar dialog box. Icon sets are only displayed graphically.

Sample Values

Visio uses the callout master shape as a thumbnail in the Edit Text dialog box, in the Edit Data Bar dialog box, and in the Edit Icon Set dialog box. The master shape also appears in the Data Graphics task pane as part of the data graphic thumbnails. To help your users understand how your callout displays information, choose an appropriate sample data value for the shape.

Callout Sizing

Visio applies special formulas to your callout shape to control its size and position relative to the parent shape in the drawing. In general, these formulas size the callout to match the width and height of the parent shape. To specify a fixed size or a size controlled by logic within the callout, place GUARD expressions in the Width cell or in the Height cell in the callout, or in both cells. In Figure 17, in the first example, the Width cell value is matched to the width of the parent shape, but the Height cell value is determined by the callout. Also in Figure 17, in the second example, both the width and height remain fixed.

Figure 17. Callout sizing examples

Callout sizing examples

Margins

Callout shapes are often stacked together or aligned along the edges of the parent shape. This may make the geometry or graphical images in the callouts appear crowded. It is often helpful to build a margin into the callout shape's geometry or image strip. The icon set example, discussed previously in this article, includes a margin to inset the geometry of the callout, as shown in Figure 18.

Figure 18. Callout margin example Geometry sections

Callout margin example Geometry sections

In this example, a user-defined cell named Margin was created to specify the spacing to be used. When you use fixed dimensions in a shape, include a factor for the page scale so that the shape is usable in scaled drawings. You can do this by multiplying the fixed dimension by the value of the DropOnPageScale cell.

Figure 19. Callout margin example user-defined section

Callout margin example user-defined section

Protection

When you design callout shapes, you must decide what you want to allow your users to manipulate in the callout after they apply it to a parent shape. The Protection section in the ShapeSheet enables you to lock down specific behaviors or properties in the callout shape. Table 7 lists some common protection cells that you can use with data-graphics callouts.

Table 7. Protection cells useful in Data Graphics callouts

Cell

Explanation

LockAspect

Useful for icon sets if the Width cell and the Height cell are not protected with the GUARD function.

LockFormat

Prevents users from making formatting changes to the callout.

LockCustProp

Prevents users from deleting essential Shape Data properties from the callout.

LockGroup

Prevents users from deleting subshapes that make up the callout.

LockFromGroupFormat

Prevents formatting changes made by users to the target shape from also being applied to the callout. Direct formatting of the callout shape is still allowed.

LockThemeColors

Prevents color themes from changing the formatting of the callout.

LockThemeEffects

Prevents effect themes from changing the formatting of the callout.

It might also be useful to put GUARD expressions in specific cells, such as formatting cells, to preserve particular behaviors and effects built into the callout shape.

Performance, Memory, and File Size

Because data-graphics callouts are Visio shapes and can contain complex graphics, they can significantly affect the size and responsiveness of a Visio drawing. If an average callout shape includes two subshapes and an average data graphic includes three callouts, Visio adds nine shapes to the document every time you apply a data graphic to a target shape. For some drawing types, such as flowcharts, the data-graphics shapes are far more complex than the shapes that constitute the drawing itself. The file size and memory requirements for a drawing that contains data graphics might be an order of magnitude larger than those of a drawing without data graphics. This affects the performance of the document.

The most important factor that influences performance, memory, and file size is the number of shapes per callout. Ideally, each callout should be a single shape. If you must combine multiple callout shapes into a group, ensure that the group itself is used for its geometry or text. Shapes support multiple geometry sections, so an additional shape is often not necessary. You can individually show or hide each geometry section based on the configuration of the callout. Additional shapes are necessary when a callout needs multiple formats or pieces of text, but try to keep the total number of shapes to a minimum. Also, avoid creating groups nested inside other groups.

Another performance factor is the time required for Visio to add new ShapeSheet cells to the callout when you use it in a drawing. Visio generates several additional user-defined cells to implement some of the data graphics behavior in the callout. Including these cells in the callout master shape saves time and file size. Table 8 lists named rows that you must add to callout masters.

Table 8. Callout user-defined cells used by data graphics

Row

Value

User.visDGCalloutItem

blank

User.visDGDefaultPos

blank

User.visDGStackHeight

blank

If you design target shapes to work with data graphics, you can add some of the named rows listed in Table 9 to target masters.

Table 9. Target-shape user-defined cells used by data graphics

Row

Value

User.visDGDisplayFormat

blank

User.visDGDefaultPos

blank

User.visDGCBVFill

blank

User.visDGOldColors

blank

User.msvThemeColors

blank

User.msvThemeEffects

blank

By pre-creating the user-defined cells needed by data graphics, you can reduce the time needed to apply data graphics to shapes.

One final performance issue to be aware of is the use of the ShapeSheet functions TEXTWIDTH and TEXTHEIGHT. These functions calculate the geometric boundary of shape text—which is useful information for precisely arranging text and geometry together. However, they require Visio to fully compose and lay out the shape text each time the function is evaluated. These functions are very expensive relative to other ShapeSheet expressions, so use them sparingly.

Hidden Masters and Removing Hidden Information

The built-in data-graphic–callout masters in Visio are hidden—their Hidden property is set to True. Marking them in this way hides the masters in the Document Stencil in the Shapes window. It also reduces the chance that a user will accidentally use the callouts outside the context of the Data Graphics feature. You can mark callouts as hidden by programmatically setting the Hidden property on each callout master to True.

Whether you do or do not set the Hidden property, the Remove Hidden Information feature in Visio deletes callout masters from the document if they are not currently in use in the drawing. You can prevent Visio from deleting a master by adding a special user-defined cell to the page sheet of the master. Add the named row User.msvRHIPreventRemoval, and set its value to 1.

Examining Built-in Callout Shapes in Visio

Visio provides a number of text callouts, data bars, and icon sets for use with the Data Graphics feature. These callouts provide useful examples and starting points for custom callout shapes. To examine a built-in callout, use it in a data graphic and then apply the data graphic to a shape on the page. Visio adds the callout master to the document. Because the master is hidden, you must use the Drawing Explorer window (from the View menu) to see and access the shape.

Conclusion

This article describes ways to extend the Visio Data Graphics feature by customizing data graphics. You can achieve simple customizations by building and configuring new data graphics, using the Data Graphics feature itself. You can create more advanced customizations by creating callout shapes to use in data graphics. Together, custom data graphics and custom callout shapes offer many opportunities for new visualizations of data.

Additional Resources

For more information, see the following resource: