Creating a Command Bar (Windows Embedded CE 6.0)

  • Article

1/6/2010

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. The command bar usually is 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 that 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 CommandBar_Create function. Windows Embedded CE registers this class when it loads the DLL for the common controls. You can use the InitCommonControls function to ensure that this DLL is loaded. The following illustration shows a Windows Embedded CE command bar.

Ee501935.8c77f58e-16ac-47e6-9a72-8f76210c6eed(en-US,WinEmbedded.60).gif

To create a command bar

  1. Create the command bar 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 Embedded CE automatically adds the Close button.

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

The following table shows how to manipulate a command bar.

To Call

Add the Close (X), Help (?), and OK buttons to the command bar. At a minimum, 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 you create a separator, specify TBSTYLE_SEP as the fsStyle member of the TBBUTTON structure that you pass in the lpButtons 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

Add ToolTips that describe the buttons on the command bar.

CommandBar_AddTooltips

Determine whether 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 you modify a menu bar on the command bar.

CommandBar_DrawMenuBar

Align the Close (X), Help (?) and OK buttons on the command bar.

CommandBar_AlignAdornments

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

Note

Do not use 0xFFFFFFFF as the command identifier of a command bar. 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 that are 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 Close buttons to the command bar.
CommandBar_AddAdornments (hwndCB, WM_HELP | CMDBAR_OK, 0)

Command bars do not resize themselves automatically when you resize a main window. To resize a command bar together 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 the CommandBar_AlignAdornments function. If you do not perform this procedure, the OK, CANCEL, and HELP buttons on the command bar do 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 together 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;

See Also

Concepts

Working with Common Controls
Creating Controls

Other Resources