Command Bars

A command bar is a menu bar or toolbar; from an object model perspective, these are represented by CommandBar objects. Because menu bars and toolbars are hosted within a window, you reference specific CommandBar objects via the Window object, through the Window.CommandBars property. In turn, every CommandBar plays host to controls such as buttons, drop-downs, and so on. Figure 10.5 shows the Solution Explorer tool window with its command bar highlighted.

Figure 10.5. The Solution Explorer tool window and its command bar.

Note that there are six buttons hosted on the command bar.

Note

Unlike the Windows collection, which holds only an instance of each open window, the CommandBars collection holds instances for every single registered command bar, regardless of whether the command bar is currently being shown in the window.

The VB code in Listing 10.9 queries the CommandBar object for the Solution Explorer window and prints out the CommandBar objects that it finds.

Listing 10.9. Querying the CommandBar Object

Imports EnvDTE Imports EnvDTE80 Imports Microsoft.VisualStudio.CommandBars Imports System.Diagnostics Imports System.Windows.Forms Public Module MacroExamples     Public Sub QueryCommandBar()         Dim windows As Windows2 = DTE.Windows         ' Grab reference to the solution explorer         Dim solExplorer As Window2 = _             windows.Item(Constants.vsWindowKindSolutionExplorer)         ' Retrieve the solution explorer's command bar object         Dim cmdBar As CommandBar = CType(solExplorer.CommandBars(1), CommandBar)         ' Start building our output string         Dim output As String = "Command bar contains: " + vbCrLf         ' Get a reference to the controls hosted in the         ' command bar         Dim controls As CommandBarControls = cmdBar.Controls         ' Count integer         Dim i As Integer = 1         ' Iterate the controls in the command bar         For Each control As CommandBarControl In controls             If control.Enabled Then                 output = output + i.ToString() + " " + _                     control.Type.ToString() + _                     ": " + control.Caption + vbCrLf                 i = i + 1             End If         Next         MessageBox.Show(output, "Solution Explorer Command Bar", _             MessageBoxButtons.OK)     End Sub End Module

Correlate the results in Figure 10.6 with Figure 10.4: Six buttons are visible on the tool window, and the code has found six items in the CommandBarControls collection (which is returned through the CommandBar.Controls property). Removing the following check against the Enabled property would result in many more controls produced in the message box:

If control.Enabled Then

Figure 10.6. Controls found in the command bar.

Notice in Listing 10.9 that you have to explicitly cast the object returned from the Window.CommandBars property: this is, interestingly, not a strongly typed property, and it returns an Object instead of an actual CommandBars instance.

Tip

Use the CommandBar.Type property to determine whether a command bar is a toolbar or a menu bar. A value of MsoBarType.msoBarTypeNormal indicates that the command bar is a toolbar, whereas a value of MsoBarType.msoBarTypeMenu indicates that the command bar is a menu bar.

The CommandBar object properties and methods are documented in Table 10.10.

Table 10.10. CommandBar Members

Property	Description
AdaptiveMenu	For menu bars, this Boolean flag indicates whether the command bar has adaptive menus enabled. (Adaptive menus, sometimes referred to as personalized menus, are menus that alter their drop-down content based on projected or actual usage by the user; the intent is to display only those commands that are useful on the menu and hide the other nonessential commands.)
Application	An object representing the parent application to the command bar.
BuiltIn	Boolean flag used to distinguish between built-in and custom command bars.
Context	A string indicating where the CommandBar is saved (the format and expected content of this string are dictated by the hosting application).
Controls	A CommandBarControls collection containing CommandBarControl objects; each of these objects represents a control displayed by the command bar.
Creator	An integer value that identifies the application hosting the CommandBar.
Enabled	A Boolean flag indicating whether the command bar is enabled.
Height	The height of the command bar in pixels.
Index	The index of the command bar in the command bar collection.
Left	The distance, in pixels, between the left side of the command bar and the left edge of its parent container.
Name	The name of the command bar.
NameLocal	The localized name of the command bar.
Parent	An object that is the parent of the command bar.
Position	An MsoBarPosition enum value used to get or set the position of the command bar (for example, MsoBarPosition.msoBarTop).
Protection	An MsoBarProtection enum value that identifies the protection employed against used modification (for example, MsoBarProtection.msoBarNoMove).
RowIndex	An integer representing the docking row of the command bar.
Top	The distance, in pixels, between the top of the command bar and the top edge of its parent container.
Type	The type of the command bar (as an MsobarType enum value; for example, MsoBarType.msoBarTypeNormal).
Visible	A Boolean flag indicating whether the command bar is currently visible.
Width	The width of the command bar in pixels.

Method	Description
Delete	Removes the command bar from its parent collection.
FindControl	Enables you to retrieve a reference to a control hosted by the command bar that fits various parameters such as its type, ID, tag, and visibility.
Reset	Resets one of the built-in command bars to its default configuration.
ShowPopup	Displays a pop-up representing a command bar.

Note

Previous versions of Visual Studio actually relied on a Microsoft Office assembly for the CommandBar object definition (Microsoft.Office.Core). Visual Studio 2005 provides its own implementation of the CommandBar object that is defined in the Microsoft.VisualStudio.CommandBars namespace, although you will find some types that carry their nomenclature over from the MS Office assembly, such as the various MsoXXX enums.