Using Command Bars

You can create a command bar to organize your application's menus and buttons.

    To create a command bar
  1. Initialize an INITCOMMONCONTROLSEX structure with ICC_BAR_CLASSES in the dwICC member.
  2. Register the command bar class by calling the InitCommonControlsEx function, and then passing in the INITCOMMONCONTROLSEX structure.
  3. Create the commands bands control by calling the CommandBar_Create function.
  4. Add controls to the command bar by calling the CommandBar_InsertMenubar, CommandBar_AddBitmap, CommandBar_AddButtons, and CommandBar_InsertComboBox functions.
  5. Add the Close and Help buttons by calling the CommandBanr_AddAdornments function, passing CMDBAR_HELP in the dwFlags parameter. Windows CE automatically adds the Close button.

In addition to creating and registering command bars, you can use command bar functions to perform the following procedures:

The window procedure for a command bar automatically sets the size of the command bar and positions it along the top of the parent window's client area. It also destroys the command bar when its parent window is destroyed. Use the CommandBar_Destroy function to destroy the command bar without destroying the parent window.

Unlike a scroll bar and a status bar, the command bar is part of the client area of your application. To determine the useable portion of the application window, use the CommandBar_Height function to retrieve the command bar's height in pixels, and then subtract the height of the command bar from the size of the client rectangle, which you obtain by calling GetClientRect.

Use the CommandBar_AddAdornments function to add the Close button (X), the Help button (?), and the OK button to a command bar. Though every command bar must have a Close button, the OK button and the Help button are optional. Do not call the CommandBar_AddAdornments function until after you have added all the other elements to the command bar.

A command bar stores the information needed to draw the button images in an internal list, which is empty when the command bar is created. Each image has a zero-based index that you use to associate the image with a button. Use the CommandBar_AddBitmap function to add an array of images to the end of the list. This function returns the index of the first new image that was added. The system includes a set of predefined command bar button with header files that define constant values for their indexes.

You can add both buttons and ToolTips to your command bar. Use the CommandBar_InsertButton function to add a single button or separator to a command bar. Use the CommandBar_AddButtons function to add several command bar buttons or separators at once to a command bar. To create a separator, specify TBSTYLE_SEP as the fsStyle member of the TBBUTTON structure you pass in the lpButton parameter. Use the CommandBar_AddTooltips function to add ToolTips describing the command bar buttons.

To create a combo box and insert it into a command bar, use the CommandBar_InsertComboBox function. This function always creates a combo box with the WS_CHILD and WS_VISIBLE styles. You can specify other supported combo box styles, as well.

To insert a menu bar into a command bar, you can use either the CommandBar_InsertMenubar or CommandBar_InsertMenubarEx function. CommandBar_InsertMenubar inserts a menu bar identified by a resource identifier. CommandBar_InsertMenubarEx inserts a menu bar identified by either a resource name or menu handle.

Note Each element in a command bar has a zero-based index by which command bar functions can identify it. The leftmost element has an index of zero, the element immediately to its right has an index of one, and so on. When you use any of the CommandBar_Insert functions, the menu bar, button, or combo box is inserted to the left of the button whose index you specify in the iButton parameter.

Although Microsoft style guidelines recommend that you always have either a command bar or a command bands control in Windows CE-based applications, you can provide users with the option to hide the command bar, as long they can retrieve it. Use the CommandBar_Show function to show or hide the command bar. Use the CommandBar_IsVisible function to determine whether a command bar is visible.

To obtain the handle of a menu bar in a command bar, use the CommandBar_GetMenu function. To obtain the handle of a submenu on the menu bar, use the GetSubMenu function.

After modifying a menu bar on the command bar, call CommandBar_DrawMenuBar to redraw the command bar. Do not use the DrawMenuBar function for menu bars on the command bar.

Note Do not use 0xFFFFFFFF as the command identifier of a command bar control. This identifier is reserved for use by the command bar.

The following code example shows how to create a command bar.

INITCOMMONCONTROLSEX icex;
icex.dwSize = sizeof(icex);
icex.dwICC  = ICC_BAR_CLASSES;
InitCommonControlsEx(&icex);

HWND hwndCB, hwnd;

hwndCB = CommandBar_Create(g_hInst, hwndParent, ID_COMMANDBAR);

CommandBar_InsertMenubar(hwndCB, g_hInst, IDM_MAINMENU, 0);

CommandBar_AddBitmap(hwndCB, HINST_COMMCTRL, IDB_STD_SMALL_COLOR, 15, 16, 16);

CommandBar_AddButtons(hwndCB, sizeof(tbButtons)/sizeof(TBBUTTON), tbButtons);

hwndCombo = CommandBar_InsertComboBox(hwndCB, g_hInst, COMBO_WIDTH, 
   CBS_DROPDOWNLIST | WS_VSCROLL, ID_COMBOBOX, 16);

CommandBar_AddAdornments(hwndCB, CMDBAR_HELP, 0);

For an example of how to use a command bar in an application, see the Cmdbar sample application described in Windows CE Sample Applications.