Make Your Own Data Graphic – Icon Sets

[visioblogs]

First published on MSDN on Jul, 20 2007

This is the third and final post in a series demonstrating how you can create data graphic callout shapes for use in Visio 2007 Professional.  The first post discussed Text Callouts . Data Bars were described in the second post.  There is also an article on MSDN that covers the full spectrum of customization possibilities for Data Graphics.

An Icon Set is one of the four ways you can visualize data using Data Graphics.  It shows information in a compact, visual form.  Icon Sets are used to convey “state” – whether some condition in the data has been met.  An Icon Set may be used to indicate exception conditions such as displaying a red flag next to a shape to indicate a problem.  Alternatively an Icon Set shows one of several possible conditions present in the shape data such as in the image above showing completion state.

A Data Graphics Icon Set can contain up to five icons.  There are two general approaches to Icon Set callout construction.  One option is to assemble five bitmaps into a shape and add logic to show the correct bitmap based on the data.  This approach is described in the MSDN article along with guidance how to do this efficiently by making an image strip.  A second option is to create the callout using Visio geometry and formatting.  This approach follows the multi-shape concept in Visio where the data controls the visibility and formatting of portions of the shape.  We will use the geometry approach for this post.

Our sample Icon Set callout is a torus or doughnut shape.  There are five possible states indicating how much of the doughnut is shown.  Technically, an Icon Set can have six states, but by convention the first state is the “not shown” state.  If the icon was intended to have some residual visual state, an image could be assigned to the “not shown” state.  Each state in the icon set corresponds to a geometry section in the shape that can be made visible when appropriate.  Also the fill color of the icon set changes with each state.  Let’s start with the minimum set of tasks to create a Data Graphic callout and then add functionality from there.

We draw a circle on the page and open its Shapesheet.  In the Shapesheet, we need to insert a User-defined section for the Icon Set properties.  Three cells are required for Icon Sets.  User.msvCalloutType identifies the shape as a Data Graphic callout of type Icon Set.  User.msvCalloutIconCount tells Visio how many icons or images are in the set.  This can range from 1 to 5.  User.msvCalloutIconNumber tells Visio the default icon to show in thumbnails of the data graphic.  Once the callout is applied to a shape, Visio uses this cell to tell the callout which icon to show.

This is all that Visio requires for a usable Icon Set callout.  If you drag this shape over to the document stencil and then make a new data graphic, you would see this callout appear in the Edit Icon Set dialog.  However, we have five icons that show the same circle.  Our next task is to add the real geometry that makes up the five icons in the set.

Our callout shape has one geometry section already.  This circle will be the outer edge of the doughnut.  We need a second circle for the inner edge.  We could draw this circle with the drawing tools, but we don’t want to create a new shape here.  All of the geometry will exist in a single callout shape.  The easiest method is to add the required geometry directly in the Shapesheet window.  Note that circles are represented using the Ellipse section type.  After inserting the new section, we update the A and D cells to set the size of the circle.

Now let’s tie the geometry to specific icons in the Icon Set.  User.msvCalloutIconNumber controls which icon should be displayed.  The index is 0-based, giving us a 0 to 4 range to work with.  Additionally, Visio uses the value -1 to indicate that no icon should be shown.  As a best practice, we will not show any icon for any value outside the 0 to 4 range.  If we glance back at the example at the top of the page, we see that the full doughnut geometry is intended to be shown for index values 0 and 4.  A partial doughnut is shown for index values 1, 2 and 3.  Our two geometry sections should only be visible when the index is 0 or 4.  We control the visibility through this formula added to the NoShow cell for each section.

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

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

This is a common expression for Icon Sets.  The OR function can have any number of conditions in it, so showing the geometry section for an additional index value would be as simple as adding one more condition to the OR function arguments.  We can test our expression by typing various numbers into User.msvCalloutIconNumber to see geometry appear and disappear.

We need an additional geometry section for each of the partial doughnut icons.  You need to understand a little about how Visio defines elliptical arcs to get the geometry formulas correct.  The basic idea is that you must specify the end point of the arc as well as a point along the arc’s path.  Also note that changing the row type of a path (to switch from LineTo to EllipticalArcTo) can reset the shape’s alignment box.  We need to prevent that by setting the LockCalcWH cell to 1 in the Protections section first.  Here are the three geometry sections needed:

To display these icons at the right time, we need to tie their NoShow cell to User.msvCalloutIconNumber.  Here are the expressions for geometry sections 3, 4 and 5 respectively:

Geometry3.NoShow = IF(User.msvCalloutIconNumber=1,FALSE,TRUE)

Geometry4.NoShow = IF(User.msvCalloutIconNumber=2,FALSE,TRUE)

Geometry5.NoShow = IF(User.msvCalloutIconNumber=3,FALSE,TRUE)

Now our callout shape shows the correct geometry for each value of User.msvCalloutIconNumber.  Next we will make the fill color change with the index value as well.  Our doughnut should be white for index 0, a reddish color for index 1 and a green color for index 4.  Between 1 and 4 the color transitions from red to green.  This is accomplished by using the BLEND function.  For BLEND the two color extremes are specified along with a value between 0 and 1 to determine the balance between the colors.

FillForegnd = IF(User.msvCalloutIconNumber=0,1,BLEND(RGB(208,81,81),RGB(146,208,80),(User.msvCalloutIconNumber-1)/3))

Once the color is set up, we set the LockFormat cell to 1 to prevent changes by the user or theming.  Our callout now produces all the icons as intended.  One final step is to lock down the size of the callout shape so that it does not stretch when applied to a target shape.  The following formulas are added to the Width and Height cells.  Note that DropOnPageScale allows the icon to work in both scaled and unscaled drawings.

Width = GUARD(0.25 in*DropOnPageScale)

Height - GUARD(0.25 in*DropOnPageScale)

This callout shape is complete and can be dragged into the Document Stencil to create a master shape.  If you open the Data Graphics task pane (Data > Display Data on Shapes) and create a new data graphic, you can add a new Icon Set to see that the callout is available for use.  One item to point out is that the second icon is shown at a different scale than the others.  For the preview image, Visio zooms to fit the visible geometry into the available image size.

We can continue to embellish the callout shape if desired.  It would be nice to set up the geometry of the icons so that it does not extend all the way to the edge of the callout shape.  Leaving a small margin makes everything look better when Visio stacks several Icon Set callouts on top of each other.  This requires changes to the geometry expressions to account for margin.  An example of this can be found in the attached Visio document.

This concludes our series on building custom Data Graphic callouts.  There are more tips and tricks about Data Graphic callout construction in the MSDN article.  If you would like to see more on this feature or other Visio 2007 features, please send us an e-mail or post a comment.

Icon Set Sample 2.vsd