When you’re developing your own smart shapes for Microsoft Visio, you’ll often want to give the end user of your shape the ability to change some options. You may have a preset selection of colors, or you may want parts of the shape to appear and disappear when the user selects an option. In general, you’ll want to make your shapes configurable to avoid adding many copies of your shape to a stencil with only small variations.

In this short tutorial, I’ll show how to use the shape sheet to add an option to a shape that enables a user to change its border thickness by selecting a thickness from a preset list of options.

First off, we’ll add a standard rectangle to the drawing area. This will be our basic shape for this exercise, but it could be a much more involved shape.

The initial shape

First off, enable the Visio Developer Ribbon. With your shape selected, open the _Show Shapesheet__ pulldown and select Shape:

Opening a smart shape's Shapesheet

This will bring up the Shapesheet for the selected shape:

The shapesheet

For basic smart shapes, the Shapesheet is where most of your work will take place. Note that the Shapesheet has many different sections, covering areas such as:

  • Shape transform: the dimensions and location of the shape
  • User-defined cells: list of values created by the developer that have special functions (we’ll soon be using this)
  • Geometry: the lines that make up the shape, which can be changes programmatically
  • Line Format and Fill Format: line and fill presence, colors, thickness and rounding. This has the same functionality as the “Format shape” window, only through fields in the Shapesheet,
  • Character, Paragraph, Tabs and Text block format: everything to do with the text inside the shape.

In order to enable the user to select option on our smart shape, the first thing we’ll do is add a user-defined cell. To do so, right-click the user-defined cell User.visVersion and select Insert Row:

Adding a user-defined cell

This will create a new row called User.Row_2. Change the name Row_2 to thickBorder, and leave the value at 0 (zero). You don’t need to put anything in the Prompt column.

Our smart shape now has a new user-defined cell, but it doesn’t affect anything yet. We will now add an option to the smart shape’s context menu that allows the user to change the value of the user-defined cell thickBorder. The options in the smart shape’s context menu are called Actions. In order to be able to add actions, we must first add an Actions section to the Shapesheet. To do so, with the Shapesheet open, click the button Insert in the developer ribbon:

Adding a section to the shapesheet

A window will popup allowing you to select the type of section to add. Add an Actions section:

Adding an actions section to the shapesheet

The new Actions section will appear in the Shapesheet and it looks like this:

The Shapesheet

There is one action there already, which we will redefine.

  • Change the action’s name from Row_1 to setBorder.
  • In the Action column, fill out =SETF(GETREF(User.thickBorder), NOT(User.thickBorder)). When the action in the context menu is selected, this code sets the value of the user-defined cell thickBorder to the opposite of what it was. That is, if the value was zero (or false), it becomes true. If the value was true, it becomes false.
  • In the Menu column, fill out Thick Border. This is the action text that will appear in the context menu.
  • In the Check column, write =User.thickBorder. This defines when a check mark appears next to the option text in the context menu. When the value for the user-defined cell thickBorder is non-zero (or true), a checkmark will appear. When the value is zero (or false), no checkmark will appear.

Now right-click on the shape in the drawing area. Your new action will appear in the context menu:

New action in the shape context menu

We have now connected our user-defined cell to a custom action in the smart shape’s context menu. All that remains now is to show the correct border thickness depending on the user-defined cell’s value. To do this, find the section titled Line Format.

The Line Format section in the Visio Shapesheet

In this section, the value for LineWeight is currently THEMEVAL("LineWeight", 0.24pt). That is, the THEMEVAL function sets the thickness of the lines of our shape to the default line thickness of the current theme, or to 0.24pt if there is no theme selected. We’ll want to change this formula to do two things. First, it must set the thickness of the shape’s line depending on the value of our user-defined cell, and then it must make sure that the user cannot change the line thickness manually through the shape formatting dialog.

To achieve this, we set the formula for LineWeight to GUARD(IF(User.thickBorder, 5pt, 1pt)). This formula has two important bits to understand. The IF function takes three arguments, where the first argument is the name of the variable to check (our user-defined cell). The IF function returns the value of the second argument if the variable’s value evaluates to true, or the value of its last argument if the variable’s value evaluates to false. The result of the IF function is passed through the GUARD function, which makes sure that the user cannot change the thickness of the shape lines manually through the shape formatting dialog.

See for yourself! You can now right-click the shape and click your new action in the context menu, causing the thickness of the shape lines to change. In addition, it’s not possible to go into Format Shape and change the line thickness. The thickness will always return to its default value.

Happy developing!