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 MembersProperty | 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. |