Command Usage

Unlike Microsoft Office, which has separate application environments for each product, the Visual Studio common development environment is a global one into which several products and their commands set contribute. The functionality available to the user at any given time is context-based, which reduces complexity in the integrated development environment (IDE).

When a user’s context changes--such as when switching from a design window to a code editing window--functionality unrelated to the new context disappears while new functionality surfaces, together with related dynamic information such as Properties and the Toolbox. The user should not notice the swapping of the available command set; if the user is distracted or confused by commands appearing or disappearing then the UI design needs adjustment.

The user’s current context is clearly and consistently indicated in the IDE title bar, the Properties window, and the Property Pages dialog box. All other tool windows and dialog boxes are also updated as the user’s context changes in the IDE.

Command bars allow for flexibility in the UI; the Visual Studio environment inherently displays only the main menu and the toolbar.

The main menu and the default toolbar can be customized and even hidden, though the main menu bar cannot be removed. Other command bars appear and disappear based on the state of the application. Tool windows in the IDE may have command bars attached to their window edges.

Content and command visibility

Commands exist in the following scopes: Environment, Hierarchy, and Document. Know each scope in order to have confidence in command placement.

Commands in the Environment scope establish primary context and are shared between multiple contexts. They alter the visibility or arrangement of documents and tool windows. Among the commands in the environment scope are New Project, Connect to Server, Attach Process, Cut, Copy, Paste, Find, Options, Customize, New Window, and View Help.

Commands in the Hierarchy scope manage hierarchies in Visual Studio including Project, Team, and Data. They relate to a project’s subcontext--e.g., Debug, Built, Test, Architecture, Analyze. Among the commands in the Hierarchy scope are Add New Item, New Query, Project Settings, Add New Data Source, Launch Performance Wizard, and New Diagram.

Commands in the Document scope act on the contents of a document such as code, design, or work item query (WIQ). They also act on the view of a tool window or are otherwise specific to that tool window. Document scope commands also act on the file objects that are themselves hierarchy-specific such as Remove from Project. Among the commands in the document scope are Refactor.Rename, Create Copy of Work Item, Expand All, Collapse All, and Create User Task.

Command placement decisions

Once you've decided to create a command you'll need to determine its appropriate placement and whether to create a keyboard shortcut. Follow this decision path to establish where to place the command:

Command placement in menus

Visual Studio’s architecture allows VSPackages to place commands anywhere in the UI. There are placeholders for suggested locations where VSPackages can define their own commands. Although VSPackages can add to the existing groups of environment commands, consider the usability repercussions before doing so.

The main menu bar should be the standard location for commands of any package that contribute to the UI. The main menu bar differs from other command bars because the environment uses it to control visibility of commands; all other command bars simply disable commands that are out of context, whether those are placed on a menu or on a toolbar.

The environment defines a set of commands built into the main menu bar that are common across the entire integrated development environment (IDE) and multiple task domains. These commands are always visible regardless of which VSPackages are loaded into the environment. Although VSPackages may extend this set of commands, the command set from each product and the placement of their commands is the responsibility of each team.

Main menu structure

The structure of the Visual Studio main menu can be broken down into the following categories:

• Basic menus: File, Edit, View, Tools, Window, Help

• Project-specific menus: Project, Build, Debug

• Context-specific menus: Team, SQL, Data, Test, Architecture, Analyze

• Document-specific menus: File, Edit, View, Tools, Window, Help

Main menu ordering

The core menus should bookend the rest of the commands; File, Edit, and View should always be to the left, whereas Tools, Window, and Help should always be to the right.

Creating a new menu

Before adding a new top-level item consider placing the command in an existing top-level menu. When adding a new top-level menu be sure to place it in the correct location. Decide whether the menu is specific to project, context, or document. Keep the name of the top-level menu concise and use only one word.

When designing main menus, adhere to these rules:

• The name of your menu should be one word; for example, “Test” instead of “Unit Test”.

• Do not exceed 25 top-level items in a given context.

• Menus should never exceed 600 pixels in height.

• Evaluate a main menu in multiple contexts, such as in the Ultimate SKU and the General Profile.

• Flyout menus are acceptable.

• Flyout menus should contain at least three items and no more than seven, and have at least one separator.

• Flyout menus should go only one level deep--never use cascading flyouts.

• Use no more than six separators.

• While it is not required to have each grouping in the figure, adding additional groupings is restricted.

• Each grouping should have between two to seven menu items.

Context menus

Placing too much functionality within the context menus results in a difficult-to-learn interface; all major functionality should be available through the main menu bar. Placement of commands should be reconciled with existing commands to avoid duplicate commands. For context menus, the shell defines standard menu groups that should be included depending on whether the context menu is for the solution, a project node, or a project item.

When designing context menus, adhere to these rules:

• Do not exceed 25 top-level menu items. Five of these placements are reserved for partner teams, so DevDiv teams should limit context menus to 20 items.

• Menus should never exceed 600 pixels in height.

• When evaluating a context menu be sure to review it in the Ultimate SKU in a variety of differing contexts.

• Flyout menus are acceptable.

• Flyout menus should contain at least three items and no more than seven, and have at least one separator.

• Flyout menus should go only one level deep--never use cascading flyouts.

• Use no more than six separators.

• See the below illustration for how to order groupings. Although it is not necessary to include each grouping in the illustration, adding more groupings is restricted.

Grouping structure for main menus and context menus

Command placement in toolbars

General toolbars

When designing and arranging toolbars, follow these standards:

• If the commands you are placing on a toolbar are specific to an editor or design surface and are likely to be used often, place an embedded toolbar at the top of the document window instead of a separate toolbar.

• Don’t use more than one verb per button. One button = one action.

• If commands are similar enough that they share an icon, choose the most context-appropriate icon for the toolbar.

• Spell out a command only if it needs to be reinforced with the label.

• Use a combo box exclusively for properties that will be switched multiple times in one session. Otherwise, expose the property elsewhere.

• The width of a combo box should equal the width of the longest item within the box + 30%. For instance, if the longest item is 200px, then the combo box should be 260px wide.

• Limit the use of separators and don’t place a separator next to a drop-down. The shape of the drop-down itself acts as a visual separator.

• Icon groups should contain 3-6 icons.

• If qualifiers result in multiple useful commands, use a split button that stores the last setting:

Product-specific toolbars

Each product can provide a default toolbar that contains frequently used and important commands, and each product's default toolbar should appear the first time Visual Studio is started after the product is installed. While each product can provide a default toolbar, many products correctly position their commands on an embedded toolbar within the document editor/designer.

Products should also leverage shared command groups and menus provided by the IDE. Each shared command group is placed in a shared menu meant to organize related commands in a meaningful way for the user. It is important to leverage this shared command structure in order to reduce complexity.

Global toolbars

Global toolbars are required to fit on one row right out of the box. When creating a new global toolbar follow the guidelines for that toolbar type:

• Document-specific toolbars appear when a certain file type is active and disappear when a different file type becomes active.

  • Document-specific toolbars may not have more than 12 buttons.

  • The total width of the toolbar may not exceed 300 pixels.

  • Each toolbar has 24 pixels in common controls (gripper, overflow).

  • Each toolbar button is 22 pixels wide including padding. Making the icon a split button adds another 11 pixels of width.

  • Each file type can have either one embedded toolbar or one document-specific global toolbar, but not both.

  • Duplication of commands across toolbars is allowed.

• Context-specific toolbars appear when a certain context is set and tend to stay active for extended periods.

  • Limit each toolbar to 3-5 buttons. Remember that each toolbar must share space with at least three other context-specific toolbars.

  • The button limit for all context-specific toolbars is 18.

  • If most users won't consistently employ this toolbar's commands when the context is active then don't associate this toolbar with a context.

  • Ensure that the toolbar disappears when exiting context. None of these toolbars should appear on startup.

• Toolbars with no context never appear automatically; these show only when the user activates them. Keep the maximum width below 200px.

General organization and shell-defined groups

Use existing shared commands, command groups, and menus. If a new command needs to be defined, try to place it in an existing shared command group. If a new group needs to be defined, try to place it in an existing shared menu close to a related command group before creating a new top level menu. This reduces command complexity while ensuring consistent command placement in the IDE.

The shared Format menu, typically shown while in the context of designer-style document windows, is illustrated in the following image:

Menu groups

Defining and placing themes

When defining and placing commands, reuse shared commands (in SharedCmdDef, ShellCmdDef) by adding those to the CMDUSED section in the command table compiler (.ctc) file. This section is meant to tag shared commands so that they aren’t removed during the CTC compiler merge process.

If a new command must be defined, place it close to related shared commands in an existing shared command group--such as SharedCmdPlace or ShellCmdPlace--or within a newly created command group.

If a new command group must be created, place it within an existing shared menu--such as SharedCmdPlace or ShellCmdPlace--and in close proximity to a related command group.

Create a new menu only if there are no related commands in an existing shared menu. Place new top-level menus in the appropriate order in the top level menu structure.

Reducing and reusing commands

Although commands are typically shown based on context--reducing the number of commands the user sees at any given time--existing shared menus and command groups should be reused to ensure that the command structure remains relatively stable between changes in context.

Reusing shared commands and placing new commands close to related shared commands reduces IDE complexity and creates a more user-friendly experience.

Command naming conventions

Consistent command naming is critical for users to find and execute commands using the command line or bind to a keyboard shortcut. It also helps the user understand what purpose a command serves when it is displayed on a toolbar or in a cascading or context menu.

To ensure consistent command naming in the integrated development environment (IDE), construct command text so that it is easily localizable. Be concise with the command text; use no more than three words and avoid combining words.

When creating command text take into consideration where the command is placed. Is it in a main menu or in a context menu? Is it in a top-level or in a flyout? For example, if you were to group text align commands (left, right, center, justify) in a flyout, the top-level command should be "Align", with the flyout commands being listed as "Left", "Right", "Center", "Justify"; the flyout commands should not be listed as "Align Left", "Align Right", etc., as that would be redundant.

List your command using title-style capitalization to be consistent with the product's legacy commands. For simplicity, avoid the use of phrases in tooltip text.

Using icons with commands

Be sparing in the use of icon pairing with commands. Although associating a unique image with a command hastens the user's ability to identify that command, visual clutter and inefficiency occur with image overuse. The following rules help when deciding whether to create a command icon.

Use an icon with a command only if:

• The same command has an icon associated with it in another prominent Microsoft product, such as a Microsoft Office application.

• The command will be placed in a default editor toolbar.

• The command won't be placed on a toolbar but is a specialty command that users are likely to add to their toolbars using the Customize command on the menus.