Customizing the Menus and Toolbars in the Microsoft Office Web Components
This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
Michael Stowe
Microsoft Corporation
April 2001
Applies to:
Microsoft® Office XP Web Components
****Summary:****Microsoft Office XP Web Components allow you to customize their default toolbars and shortcut menus. This article provides several examples that illustrate how to customize the built-in toolbars and shortcut menus. (7 printed pages)
Download Odc_ocWebCustmUI.exe.
Contents
Introduction
Customizing Shortcut Menus
Customizing the Toolbar
Conclusion
Introduction
The Microsoft® Office XP Web Components allow you to customize their default toolbars and shortcut menus. This article provides several examples that illustrate how to customize the built-in toolbars and shortcut menus. Specific topics include:
- Creating a customized shortcut menu.
- Modifying the default shortcut menu.
- Adding a submenu to the shortcut menu.
- Customizing the toolbar with built-in commands.
- Adding custom commands to the toolbar.
Customizing Shortcut Menus
Customizing the shortcut menus in the Office Web Components involves working with the BeforeContextMenu and CommandExecute events. You place the code to create your customized shortcut menu in the BeforeContextMenu procedure. You place code that handles the custom menu entries in the CommandExecute Event.
Creating a Custom Menu
The shortcut menus in the Office Web Components consist of nested arrays. The menu itself is a one-dimensional array that contains the commands listed on the menu. Each command is a two-dimensional array. The first dimension contains the caption to display on the menu. The second dimension contains a reference to the command to be displayed. You can refer to a built-in command, or assign a name to the command to use later when handling menu selections.
Once you have created the array containing your menu, you set the Value property of the Menu variable to the array. The Menu variable, which is automatically passed into the BeforeContextMenu event, refers to the menu for the Web component.
To see an example of how to display a shortcut menu containing only custom commands, see the Custom Menu 1.htm file in the sample download.
Including Built-in Commands in Your Shortcut Menu
Your custom shortcut menu can refer to built-in commands in addition to commands of your creation. Each built-in command corresponds to a built-in constant. The OCCommandId, ChartCommandIdEnum, PivotCommandId, and SpreadsheetCommandId constants contain lists of the supported commands for each of the Office Web Components. You can use the Object Browser to view the list of commands for each constant.
To refer to a built-in command, refer to the constant in the second dimension of the array for the custom menu command. There are two ways to do this. One method is to include the Long value of the constant as the second array dimension. The other method is to refer to the name of the constants with the string owc concatenated to the beginning of the command. The following example illustrates the two equivalent methods that you can use to add the Copy command to the array that will be used as your shortcut menu. Note that this example assumes a variable named owcContants has been initialized to the constants for the Office Web Components.
vntMyMenu(0) = Array("&Copy", 1002)
vntMyMenu(0) = Array("&Copy", "owc" & owcConstants.ocCommandCopy)
To see an example of how to display a shortcut menu containing built-in commands, see the Custom Menu 2.htm file in the sample download.
Building a Submenu Into Your Shortcut Menu
Adding a submenu to your custom shortcut menu allows you to group related sets of commands without creating a lone set of choices. A submenu is simply a menu within a menu. To create a submenu, you create an array that contains the commands on the submenu, and then you pass the array to an item on the top level menu.
To see an example of how to display a shortcut menu containing a submenu, see the Custom Menu 3.htm file in the sample download.
Adding Commands to the Default Shortcut Menu
In some situations you may want to add a command or two to the existing shortcut menu instead of building the entire menu yourself. The main advantage to this approach is that you don't have to write the code that handles the built-in commands that already exist on the menu.
To do this, you must assign the existing menu to an array, and then use the ReDim statement with the Preserve keyword to resize the array. You can add your commands once the array has been resized.
To see an example of how to add commands to the default shortcut menu, see the Custom Menu 4.htm file in the sample download.
Adding a Separator to a Custom Menu
Separators can be useful if you want to group a set of related commands without creating submenus. To create a separator, set a member of your menu array to the Empty keyword.
To see an example of how to add a separator to the shortcut menu, see the Custom Menu 4.htm file in the sample download.
Handling Menu Clicks
Once you have built your shortcut menu, you have to write code to determine what happens when a user selects a menu item. This code is stored in the CommandExecute event procedure.
The Command argument, which is automatically passed into the CommandExecute event, contains the command that is to be executed. To determine whether or not you need to handle the incoming command, use the VarType function on the Command argument in an If..Then statement. If the Command argument evaluates to a type of vbString, then you need to write code that handles the command.
The easiest way to handle the command is to implement a Select Case construct. You compare the Command argument to each of the command identifiers in the menu array. If it is a custom command, simply call a procedure that you have established for the command. If it is a built-in command that you have added to your custom menu, use the Execute method to execute the command.
Customizing the Toolbar
Each of the Office Web Components contains a customizable toolbar. However, other than the Toolbar property, the Office Web Components object model contains no members that pertain to customizing their toolbar. Why? The toolbar is actually a Microsoft Windows® common control.
In order to customize the toolbar, you have to use the properties and methods of several objects, collections, and controls that are outside of the Office Web Components object model. These include the following: the Toolbar object, the Buttons collection, the Button object, the ImageList control, and the ListImages collection.
Adding Built-in Commands to the Toolbar
The steps that are required to add a built-in command to the toolbar vary depending upon whether or not the command already has an icon in the toolbar's ImageList control.
The following commands are already stored in the ImageList control associated with the toolbar or each of the Web components.
Table 1. Commands already in the ImageList control
| Command | Command Identifier |
|---|---|
| Undo | ocCommandUndo |
| Cut | ocCommandCut |
| Copy | ocCommandCopy |
| Paste | ocCommandPaste |
| Commands and Options | ocCommandProperties |
| Help | ocCommandHelp |
| Export To Excel | ocCommandExport |
| Sort Ascending | ocCommandSortAsc |
| Sort Descending | ocCommanSortDesc |
| Field List | ocCommandChooser |
| AutoFilter | ocCommandAutoFilter |
| AutoCalc | ocCommandAutoCalc |
| Collapse | ocCommandCollapse |
| Expand | ocCommandExpand |
| Refresh | ocCommandRefresh |
| AutoSum | ssCommandAutoSum |
| AutoFilter (Spreadsheet only) | ssCommandAutoFilter |
| Refresh All | ssCommandRefreshAll |
| Subtotal | plCommandSubtotal |
| Calculated Totals and Fields | plCommandCalculated |
| Hide Details | plCommandHideDetails |
| Show Details | plCommandShowDetails |
| Show Top/Bottom Items | plCommandContditionalFilter |
| Show As | plCommandShowAs |
| Show/Hide Legend | chCommandShowLegend |
| By Row/Column | chCommandByRowCol |
| Drill Into | chCommandDrill |
| Drill Out | chCommandDrillOut |
| Delete Selection | chCommandDeleteSelection |
| Chart Type | chCommandChartType |
| Chart Wizard | chCommandShowWizard |
The command identifiers that begin with the prefix oc apply to one, but not necessarily all, of the Office Web Components. Command identifiers that begin with ss apply only to the Spreadsheet Component. Command identifiers that begin with pl apply only to the PivotTable Component. Command identifiers that begin with ch apply only to the Spreadsheet Component.
Adding Built-in Commands that Already Appear in the ImageList for the Toolbar
The commands listed in Table 1 represent the commands that are listed on the default toolbars of the Office Web Components. If you want to add one of these commands to the toolbar, you must first remove that command from the toolbar. In other words, the command cannot be added to the toolbar twice.
One of the few situations where you would add one of the commands listed in Table1 to the toolbar would be if you only a few of the default commands to be available to the user. For example, you could remove all of the commands from the PivotTable toolbar, and then add the Refresh command (ocCommandRefresh) to the toolbar.
You use the Add method of the Buttons collection to add a built-in command that already appears in the image list. You must specify values for the index, key, and imagearguments of the Add method. The index argument specifies the location of the new button on the toolbar. For the index and key arguments, you must specify the command identifier, with the string owc concatenated to the beginning of the identifier.
To see an example of how to add some of the commands listed in Table 2 to the toolbar, see the Custom Toolbar 1.htm file in the sample download.
Adding Built-in Commands That Do Not Already Appear in the ImageList for the Toolbar
In order to add a built-in command that is not listed in Table 2 to the toolbar, you must first add a picture that represents the command to the toolbar's image list. To do this, you use the Add method of the ListImages collection. You must specify values for the key and picture arguments of the Add method. The value specified for the key argument will be used later to identify the image. You can specify any text that is unique among the keys in the ListImages collection.
The value specified for the picture argument will be used as the image displayed on the toolbar button. Use the LoadPicture function to load the image into the ImageList control.
Note Microsoft JScript® does not contain the LoadPicture function.
Once the image has been added to the ListImages collection, you use the Add method of the Buttons collection to add the command to the toolbar. You must specify values for the index, key, and imagearguments of the Add method. The index argument specifies the location of the new button on the toolbar. For the index argument you must specify the command identifier, with the string owc concatenated to the beginning of the identifier. For the key argument, you specify the value that you passed for the key argument when you added the image of the command to the ListImages collection.
To see an example of how to add a built-in function that is not listed in Table 2 to the toolbar, see the Custom Toolbar 2.htm file in the sample download.
Adding Custom Commands to the Toolbar
The steps necessary to add a custom command to the toolbar are very similar to the steps needed to add a built-in command that does not appear in the image list. First, you must use the Add method of the ListImages collection, specifying values for the key and picture arguments. Next, you use the Add method of the Buttons collection to add the command to the toolbar, specifying values for the index, key, and imagearguments. Specify the name of your command in the key argument.
Once you have added a custom command to the toolbar, you have to write code to determine what happens when a user selects a menu item. This code is stored in the CommandExecute event procedure. You handle the custom button in exactly like you would handle a custom menu command. This procedure is discussed in the Handling Menu Clicks section earlier in this article.
To see an example of how to add a custom command to the toolbar, see the Custom Toolbar 3.htm file in the sample download.
Conclusion
The Office XP Web Components make it easy for you to customize the default toolbars and shortcut menus that you want your users to see when deploying solutions.