Creating a Command Bar

A command bar is a toolbar that can include a menu bar as well as the Close (X) button, the Help (?) button, and the OK button, and is usually found on the title bar of Windows-based desktop applications. A command bar can contain menus, combo boxes, buttons, and separators. A separator is a blank space you can use to divide other elements into groups or to reserve space in a command bar. You create a command bar to organize your application menus and buttons.

You create a command bar by using the CommandBarCreate function. Windows CE registers this class when it loads the common control DLL. You can use the InitCommonControls function to ensure that this DLL is loaded. The following screen shot shows a Windows CE command bar.

    To create a command bar

  1. Create the command bands control by calling the CommandBar_Create function.
  2. Add controls to the command bar by calling the CommandBar_InsertMenubar, CommandBar_AddBitmap, CommandBar_AddButtons, and CommandBar_InsertComboBox functions.
  3. Add the Close and Help buttons by calling the CommandBar_AddAdornments function and passing CMDBAR_HELP in the dwFlags parameter. Windows CE automatically adds the Close button.

In addition to creating and registering command bars, Windows CE supports many functions you can use to manipulate a command bar.

The following table shows how to manipulate a command bar control.

To
Call
Add the Close (X), Help (?), and OK buttons to the command bar. Minimally, every command bar must have a Close button. CommandBar_AddAdornments
Destroy the command bar without destroying the parent window. CommandBar_Destroy
Add a single button or separator to a command bar. CommandBar_InsertButton
Add several buttons or separators at once to a command bar. When creating a separator, specify TBSTYLE_SEP as the fsStyle member of the TBBUTTON structure you pass in the lpButton parameter. CommandBar_AddButtons
Determine the usable portion of the application window. GetClientRect
Subtract the height of the command bar from the size of the client rectangle. CommandBar_Height
Determine whether a command bands control is visible. CommandBands_GetRestoreInformation
Add ToolTips describing the command bar buttons. CommandBar_AddTooltips
Show or hide the command bands control. CommandBands_Show
Determine if a command bar is visible. CommandBar_IsVisible
Create a combo box and insert it into a command bar. This function always creates a combo box with the WS_CHILD and WS_VISIBLE styles. CommandBar_InsertComboBox
Insert a menu bar, identified by a resource identifier, into a command bar. CommandBar_InsertMenubar
Insert a menu bar, identified by a resource name or menu handle, into a command bar. CommandBar_InsertMenubarEx
Obtain the handle to a menu bar in a command bar. CommandBar_GetMenu
Obtain the handle to a submenu on the menu bar. GetSubMenu
Redraw the command bar after modifying a menu bar on the command bar. CommandBar_DrawMenuBar

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.

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 added. The system includes a set of predefined command bar buttons with header files that define constant values for their indexes.

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.

// Create a command bar. 
hwndCB = CommandBar_Create (hInst, hwnd, 1);

// Adds ToolTip strings to the command bar. 
CommandBar_AddToolTips (hwndCB, uNumSmallTips, szSmallTips);

// Adds 15 images to the list of button images available for use
// in the command bar.
CommandBar_AddBitmap (hwndCB, HINST_COMMCTRL, IDB_STD_SMALL_COLOR, 
                      15, 16, 16);

// Insert the menu bar into the command bar.
CommandBar_InsertMenubar (hwndCB, hInst, IDM_MAIN_MENU, 0);

// Add buttons in tbSTDButton to the command bar.
CommandBar_AddButtons (hwndCB, 
                       sizeof (tbSTDButton) / sizeof (TBBUTTON), 
                       tbSTDButton);

// Add Help, OK, and Exit buttons to the command bar.
CommandBar_AddAdornments (hwndCB, WM_HELP | CMDBAR_OK, 0)

Command bars do not automatically resize when you resize a main window. To resize a command bar along with a main window, wait until the main window receives a WM_SIZE message. Then send a TB_AUTOSIZE message to the command bar and call CommandBar_AlignAdornments. If you do not perform this procedure, the OK, CANCEL, and HELP command bar buttons will not stay flush with the right border of the window when the window size changes. The following code example shows how to resize a command bar along with a main window.

case WM_SIZE:
   // Tell the command bar to resize itself to fill the top of the
    window.
   SendMessage(hwndCB, TB_AUTOSIZE, 0L, 0L);
   CommandBar_AlignAdornments(hwndCB);
   break;