This documentation is archived and is not being maintained.

Shortcut Menu Commands

When a user right-clicks a shape on the drawing page, a shortcut menu appears that includes commands that apply to the selection. You can define commands that appear on a shape's shortcut menu and on the Actions submenu of the Shape menu. A row in a shape's or page's Actions section defines a command name and action provided by that shape or page.

For example, you could define an action called Run Program for a shape that evaluates this formula when performed:

When a user right-clicks the shape, Run Program appears on the shortcut menu. If the user clicks Run Program, Microsoft® Visio® evaluates the formula. In this case, My_prog.exe starts.

Note Action cells, like Event cells, are evaluated only when the action occurs, not when you enter the formula.

This section describes using formulas to work with shortcut menu commands. You can also customize the user interface, including shortcut menus, using Automation. For details, see https://msdn.microsoft.com/en-us/library/aa201793(v=office.10).aspx Chapter 22, Customizing the Visio User Interface.

In this section…

Defining a Shortcut Menu Command

Controlling a Shortcut Command's Appearance on the Menu

Adding Check Marks to Commands on the Shortcut Menu

Dimming a Shortcut Command on the Menu

Hiding and Showing Commands on the Shortcut Menu

Using Shortcut Commands to Change Shape Geometry: an Example

Defining a Shortcut Menu Command

You can create shortcut menu commands for almost any shape behavior that is controlled by a ShapeSheet® cell. For example, you might create shortcut commands for turning on and off various cells in the Protection section for a shape, or you might define commands that modify a shape's formatting cells.

To define a shortcut menu command for a shape or page

  1. Select a shape. On the Window menu, click Show ShapeSheet.
  • To display the page's sheet, make sure that nothing is selected, and then click
  • Show ShapeSheet
  • on the
  • Window
  • menu.
  1. If the Actions section is not already present, click Section on the Insert menu. In the Insert Section dialog box, select Actions, and then click OK.
  • If the Actions section is present but not visible, click
  • Sections
  • on the
  • View
  • menu. In the
  • View Sections
  • dialog box, select
  • Actions
  • , and then click
  • OK
  • .
  • To add additional actions, select a cell in the Actions section, right-click, and then click
  • Insert Row
  • on the shortcut menu.
  1. In the Action cell, enter the formula that you want to be evaluated when the user chooses the Action command.
  • Action 1    = SETF(GetRef(LockTextEdit), TRUE)

  • Action 2    = SETF(GetRef(LockTextEdit), FALSE)
  1. In the Menu cell, enter a command name as you want it to appear on the shortcut menu.
  • For example, you might enter the text "Lock Text" for Action 1 so that the command
  • Lock Text
  • appears on the shortcut menu, and the text "Unlock Text" for Action 2 so that the command
  • Unlock Text
  • appears below it.

To test the new command, right-click the shape or page to display its shortcut menu, and then choose the Action command you defined.

Tip After you've added an Actions section to the ShapeSheet window for a shape or page, you can define common actions quickly by using the Action command on the Edit menu. The command is dimmed until you select a cell in an Actions section. In the Action dialog box, type a name for the menu item in Menu, select an action, and click OK. The corresponding cells of the Actions section are updated. If you choose an action in the dialog box such as Go to page, the appropriate formula is entered in the Action cell.

https://msdn.microsoft.com/en-us/library/aa200979(v=office.10).aspx TOP

Controlling a Shortcut Command's Appearance on the Menu

The actions you add appear by default at the top of the shortcut menu in the order that they are listed in the Actions section. To control the appearance and position of your action command in the shortcut menu, you can use a prefix before the name you type in the Menu cell. To display your command at the bottom of the shortcut menu, use the following syntax:

To display a divider bar above the command, use the following syntax:

To create a keyboard shortcut for the command, place an ampersand (&) before the desired shortcut letter, as follows:

In addition, you can write formulas that place check marks next to commands to indicate that they've been selected, dim commands that aren't relevant for a particular context, and toggle between two mutually exclusive commands on the shortcut menu by hiding and showing the relevant command.

https://msdn.microsoft.com/en-us/library/aa200979(v=office.10).aspx TOP

Adding Check Marks to Commands on the Shortcut Menu

When you define several shortcut menu commands for a shape, you can show which one has been applied to the shape by placing a check mark beside it on the menu. To do this, you set the Checked cell of the selected Actions row to true. You can also use a logical expression to check and uncheck the command by referencing a user-defined cell.

For example, you might want to check either the Lock Text or Unlock Text commands added in the previous example. To do so, you would enter the following formula in the Checked cell of the Lock Text action:

In this case, when the value of the LockTextEdit is TRUE, the Checked cell evaluates the formula as TRUE, and a check mark is placed beside the command name to indicate that the text is locked, as shown in the following figure.

You can place a check mark beside the commands you define in the Actions section.

You can place a check mark beside the commands you define in the Actions section.

You could also enter a similar formula for the second action to check the Unlock Text command as follows:

In this example, the Unlock Text command would be checked on the shortcut menu when LockTextEdit is FALSE.

https://msdn.microsoft.com/en-us/library/aa200979(v=office.10).aspx TOP

Dimming a Shortcut Command on the Menu

To refine the shape, you can dim commands that don't currently apply to the shape. For example, when a user chooses the Lock Text command, the text is locked so that only the Unlock Text command needs to be available on the menu. To do this for the Lock Text example, you would enter the following formula in the Disabled cell of the Actions section for the Lock Text action:

You could enter a similar formula in the Disabled cell for the Unlock Text action as follows:

The result of any formula in the Disabled cell is evaluated as either TRUE or FALSE. When the Lock Text command is chosen, the value of LockTextEdit is TRUE, so the expression in the Disabled cell evaluates to TRUE, and the Lock Text command is dimmed. If the Unlock Text command is chosen, LockTextEdit is FALSE, so the expression in the Disabled 2 cell is TRUE and the Unlock Text command is dimmed.

https://msdn.microsoft.com/en-us/library/aa200979(v=office.10).aspx TOP

Hiding and Showing Commands on the Shortcut Menu

Whenever a shape has only two states or attributes that represent an either/or situation, such as the Lock Text and Unlock Text examples we've been working with, you can create the appearance of hiding and showing command names by conditionally changing the text that appears on the menu. For example, you might prefer to streamline your user interface by displaying only one command on the menu at a time: If the text is locked, the command on the shortcut menu is Unlock Text. If the text is unlocked, the command is Lock Text.

To create a command that changes on the shortcut menu, you need only one row in the Actions section. You write two logical expressions: one in the Action cell to toggle the value of LockTextEdit, and another in the Menu cell to determine which command to display based on the value of LockTextEdit:

  • Action    = SETF(GetRef(LockTextEdit),NOT(LockTextEdit))

  • Menu    = IF(LockTextEdit,"Unlock Text","Lock Text")

If the value of LockTextEdit is TRUE, setf sets it to FALSE; otherwise, the value of LockTextEdit is FALSE, so setf sets it to TRUE. The formula in the Menu cell also refers to the LockTextEdit cell: If it is TRUE, the Unlock Text command appears, and if it is FALSE, the Lock Text command is visible.

When a shape has more than two states or menu commands, users will find it less confusing if you use the Checked or the Disabled cell to indicate which commands are available.

Tip You can use the SETF function in an Event or Action cell to toggle the value of another cell between two options, or to increment values in another cell. Because the formula in an Event or Action cell is evaluated only when the event occurs, you can write a self-referential formula using the SETF function that doesn't cause a loop. For example, to toggle the value of CellA depending on the value of CellB, use the following syntax in an Events or Action cell:

To increment the value of cell by one, use this syntax:

For details about the syntax of the SETF function, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

https://msdn.microsoft.com/en-us/library/aa200979(v=office.10).aspx TOP

Using Shortcut Commands to Change Shape Geometry: an Example

You can use shortcut menu commands to control shape geometry, so that users can choose a command to change the shape's appearance. For example, you can create a single shape that represents two states: on or off, open or closed, engaged or disengaged. To do this, you create a merged shape that contains multiple Geometry sections in its ShapeSheet spreadsheet using the Combine command. Then, in the Actions section of the merged shape, you can define shortcut menu commands that control the visibility of the Geometry section that represents one state. To demonstrate, we'll create an office chair with arms that can be shown or hidden as the following figure shows.

You can define shortcut commands that appear when you right-click the merged shape. In this example, choosing the command (A) hides the geometry of one of the merged shape's component shapes.

You can define shortcut commands that appear when you right-click the merged shape. In this example, choosing the command (A) hides the geometry of one of the merged shape's component shapes.

To combine shapes into a merged shape

  1. Create the shapes you want to use in your merged shape.
  1. Select the chair shapes. On the Shape menu, point to Operations, and then click Combine.

For details about merging shapes, see https://msdn.microsoft.com/en-us/library/aa200976(v=office.10).aspx Creating and Controlling Merged Shapes in https://msdn.microsoft.com/en-us/library/aa200971(v=office.10).aspx Chapter 6, Grouping and Merging Shapes.

To add an Actions section to the merged shape and define shortcut commands

  1. Select the merged shape. On the Window menu, click Show ShapeSheet.
  1. On the Insert menu, click Section. Select User-defined cells and Actions, and then click OK.
  1. Type a name for the user-defined cell.
  • For example, type
  • State
  • to create the user-defined cell User.State.
  1. Enter the value TRUE in the user-defined cell. The initial value is TRUE so that the chair arms are visible.
  1. Select the first row in the Actions section, and then click Row on the Insert menu to create a total of two rows in the Actions section.
  1. To define the command names and corresponding actions, enter these formulas:
  • Action[1]     = SETF(GetRef(User.State),TRUE)

  • Menu[1]     = "Show Arms"

  • Action[2]     = SETF(GetRef(User.State),FALSE)

  • Menu[2]     = "Hide Arms"
  1. In the two Geometry sections that correspond to the arms of the chair, enter this formula:
  • Geometry
  • n
  • .NoShow    = NOT(User.State)
  • Geometry3.NoShow    = NOT(User.State)

  • Geometry4.NoShow    = NOT(User.State)

The Action cell formula uses the setf function to set the value of User.State to true when the Show Arms command is clicked or false when the Hide Arms command is clicked. The Menu cell defines these command names.

To hide and show paths, you enter formulas in the NoShow cell of the appropriate Geometry section that refer to the value of the User.State cell. The NoShow cell controls whether the path defined by that Geometry section is shown or hidden. In this case, the arms are both shown or both hidden, so the same formula is used in the NoShow cells of the two corresponding Geometry sections.

The not function returns TRUE if an expression is false, and if TRUE, returns FALSE. When a user clicks Hide Arms, User.State is set to false. The not function then returns TRUE so that the value of the NoShow cell is true and the path and fill for the corresponding component are hidden.

Show: