VISIBILITY_SECTION – VISIBILITY_END
Note
Beginning with Visual Studio 2008 SDK, use XML Command Table (.vsct) files instead of command table configuration (.ctc) files to define how menus and commands appear in your VSPackages. For more information, see XML-Based Command Table Configuration (.vsct) Files.
The VISIBILITY_SECTION – VISIBILITY_END section determines the static visibility of commands and toolbars. Each entry identifies a command or menu and an associated command user interface (UI) context. The visibility is initially controlled by the Visual Studio IDE without loading the VSPackage.
Once your VSPackage is loaded, the IDE relies on your commands to determine their visibility instead of the static visibility defined in the VISIBILITY_SECTION - VISIBILITY_END section. In an unmanaged VSPackage, implement QueryStatus; in a managed VSPackage, handle the BeforeQueryStatus event.
A command or menu listed in the VISIBILITY_SECTION – VISIBILITY_END section will appear only when the associated context is active. The VISIBILITY_SECTION – VISIBILITY_END section only applies to commands and menus, not to groups. Commands and menus not included in this section are always visible whenever their parent menu is active. A command or menu may be associated with multiple command UI contexts by including an entry for each command/context combination.
The Visibility Entry
Each entry in the VISIBILITY_SECTION – VISIBILITY_END section contains two fields, separated by a comma and ending with a semicolon. For example,
Item ID, Context ID;
The following table describes these fields. The last field ends with a semicolon. See "The Visibility Entry Fields" section later in this topic for more details on each field.
Field |
Description |
|---|---|
Item ID |
A GUID:ID pair that identifies the command or menu whose visibility is to be handled automatically by the Visual Studio Integrated Development Environment (IDE). |
Context ID |
A GUID that identifies the context in which to show the item. |
Visibility Example
The following is an example of how to specify visibility entries in the VISIBILITY_SECTION – VISIBILITY_END section. In this example, a command is made visible whenever a solution is loaded and a menu is made visible whenever a debugging session has started.
VISIBILITY_SECTION
// Item GUID when visible
guidMyCmdSet:cmdidMyMenuCommand, UICONTEXT_SolutionExists;
guidMyCmdSet:IDM_MY_DEBUGMENU , UICONTEXT_Debugging;
VISIBILITY_END
The Visibility Entry Fields
Each entry in the VISIBILITY_SECTION – VISIBILITY_END section has two fields separated by commas and ending with a semicolon. These fields, in order, are:
Item ID
The Item ID field identifies the command or menu for which you want to control static visibility.
Commands must have the DEFAULT_INVISIBLE and DYNAMIC VISIBILITY flags set in order for entries in the VISIBILITY_SECTION – VISIBILITY_END section to take effect. Menus always have the DYNAMIC_VISIBILITY flag set by default. See the BUTTONS_BEGIN – BUTTONS_END section for more details on specifying commands.
Context ID
The Context ID field identifies the UI context to associate with the Item ID field. When this UI context is active, the command or menu is made visible - without unnecessarily loading the VSPackage.
See the "UI Context GUIDs" and "Custom GUIDs" section in this topic for more details on what can be placed in the Context ID field.
UI Context GUIDs
The system maintains a set of UI context GUIDs that are active or inactive depending on the current state of the Visual Studio IDE. For example, when a solution is building, the UICONTEXT_SolutionBuilding context is active. When the build stops, the UICONTEXT_SolutionBuilding context is made inactive. Multiple UI contexts can be active at the same time.
The following UI context GUIDs are available by default for use in a Command Table Configuration file (.ctc). The definitions for these GUIDs are specified in the vsshell.h header file that can be included in your .ctc file. This header file is located in the VisualStudioIntegration\common\inc subdirectory of your Visual Studio SDK installation (for example, C:\Program Files\Visual Studio 9 SDK\2006.2\VisualStudioIntegration\common\inc).
Custom GUIDs
VSPackages that need to activate and deactivate a custom context identified by a custom context GUID should use the IVsMonitorSelection interface on the SVsShellMonitorSelection service to control the state of that custom context GUID. The custom context GUID can then be used in the visibility entry.
In addition, GUIDs from other sources, such as the ToolWindowGuids80 collection or a project GUID or even a language service GUID, can be used but you must add a definition for the GUID yourself before using it in the .ctc file. For example, to have your menu command be available whenever the Find and Replace dialog box is shown, create the following GUID definition in the .ctc file or an appropriate header file included into the .ctc file (the GUID shown here came from FindReplace):
#define guidFindReplace { 0xCF2DDC32, 0x8CAD, 0x11D2, { 0x93, 0x02, 0x00, 0x53, 0x45, 0x00, 0x00, 0x 00 } }
And then use the definition in the VISIBILITY_SECTION like this:
VISIBILITY_SECTION
// Command GUID when visible
guidMyCmdSet:cmdidMyMenuCommand, guidFindReplace;
VISIBILITY_END