Creating a Command Bands Control (Windows Embedded CE 6.0)

1/6/2010

The command bands control is a special kind of rebar control. It has a fixed band at the top that contains a toolbar with a Close (X) button and, optionally, a Help (?) button and an OK button in the right corner. By default, each band in the command bands control contains a command bar. You can override this default behavior, however, if you want a band to contain some other type of child window.

The following screen shot shows a Windows Embedded CE command band.

To create a command bands control

1. Initialize an INITCOMMONCONTROLSEX structure and set the dwICC member to ICC_BAR_CLASSES | ICC_COOL_CLASSES.

2. Register the command bands control class and command bar class by calling the InitCommonControlsEx function and passing in the INITCOMMONCONTROLSEX structure.

3. Create the image list to use for the band images.

4. Create the command bands control by calling the CommandBands_Create function and passing the handle to the image list handle in the himl parameter.

5. Initialize an array of REBARBANDINFO structures, one for each band in the command bands control.

6. Add the bands by calling the CommandBands_AddBands function, and pass the array of REBARBANDINFO structures in the prbbi parameter.

7. Add controls to the command bars in the bands by calling the appropriate command bar functions for the controls that you want to add.

8. Call the CommandBands_AddAdornments function to add the OK and Help buttons. When you call CommandBands_AddAdornments, the Close button is added by default.

The following code example shows how to register and create a command bands control.

HWND WINAPI CreateCmdband (HWND hwnd)
{
  HWND hwndCBar = NULL,     // The handle to the command bar control
  HWND hwndCBand = NULL;    // The handle to the command bands control
  REBARBANDINFO rbi[3];     // REBARBANDINFO structures for command bands
  HIMAGELIST hImageList = NULL; 
                            // Handle to the image list for command bands
  INITCOMMONCONTROLSEX iccex; 
                            // INITCOMMONCONTROLSEX structure
  
  iccex.dwSize = sizeof (INITCOMMONCONTROLSEX);
  iccex.dwICC = ICC_BAR_CLASSES | ICC_COOL_CLASSES;

  // Register toolbar and rebar control classes from DLL for the common 
  // control.
  InitCommonControlsEx (&iccex);

  // Create the image list for the command bands.
  if (!(hImageList = ImageList_LoadImage (
                  hInst, 
                  MAKEINTRESOURCE (IDB_BANDIMAGE), 
                  16, 
                  3,            
                  CLR_DEFAULT, 
                  IMAGE_BITMAP, 
                  LR_DEFAULTCOLOR)))
    goto error;

  // Create the command bands control.
  if (!(hwndCBand = CommandBands_Create (
                  hInst, 
                  hwnd, 
                  ID_BAND,         
                  RBS_VARHEIGHT | RBS_BANDBORDERS | RBS_AUTOSIZE, 
                  hImageList)))
    goto error;

  // REBARBANDINFO for the menu band.
  rbi[0].cbSize = sizeof (REBARBANDINFO);
  rbi[0].fMask = RBBIM_STYLE | RBBIM_ID | RBBIM_SIZE;
  rbi[0].fStyle = RBBS_CHILDEDGE | RBBS_NOGRIPPER;
  rbi[0].wID = ID_BAND_MENUBAR;
  rbi[0].cx = 150;
  
  // REBARBANDINFO for the main toolbar band.
  rbi[1].cbSize = sizeof (REBARBANDINFO);
  rbi[1].fMask = RBBIM_TEXT | RBBIM_ID | RBBIM_IMAGE | RBBIM_STYLE;
  rbi[1].fStyle = RBBS_BREAK | RBBS_GRIPPERALWAYS;
  rbi[1].lpText = TEXT("Toolbar");
  rbi[1].wID = ID_BAND_TOOLBAR;
  rbi[1].iImage = 0;

  // REBARBANDINFO for the font toolbar band.
  rbi[2].cbSize = sizeof (REBARBANDINFO);
  rbi[2].fMask = RBBIM_TEXT | RBBIM_ID | RBBIM_IMAGE | RBBIM_STYLE;
  rbi[2].fStyle = RBBS_GRIPPERALWAYS;
  rbi[2].lpText = TEXT("Font");
  rbi[2].wID = ID_BAND_FONT_TOOLBAR;
  rbi[2].iImage = 1;

  // Adds bands to the command bands control. 
  if (!CommandBands_AddBands (hwndCBand, hInst, 3, rbi))
    goto error;

  // Insert a menu bar into the menu command band. 
  if (hwndCBar = CommandBands_GetCommandBar (hwndCBand, 0))
    CommandBar_InsertMenubar (hwndCBar, hInst, IDM_MAIN_MENU, 0);

  // Add the buttons to the main toolbar band. 
  if (hwndCBar = CommandBands_GetCommandBar (hwndCBand, 1))
  {
    CommandBar_AddBitmap (hwndCBar, hInst, IDB_TOOLBAR, 11, 0, 0);
    CommandBar_AddButtons (
                  hwndCBar, 
                  sizeof (tbButtons) / sizeof (TBBUTTON),
                  tbButtons);
  }
  
  // Add the buttons to the font toolbar band.
  if (hwndCBar = CommandBands_GetCommandBar (hwndCBand, 2))
  {
    CommandBar_AddBitmap (hwndCBar, hInst, IDB_TOOLBAR, 11, 0, 0);
    CommandBar_AddButtons (
                  hwndCBar, 
                  sizeof (tbFontButtons) / sizeof (TBBUTTON),
                  tbFontButtons);
  }

  // Add the Help and Close buttons to the command bands.
  CommandBands_AddAdornments (hwndCBand, hInst, CMDBAR_HELP, NULL);

  return hwndCBand;

error:
  if (hImageList)
  {
    ImageList_Destroy (hImageList);
  }
  if (hwndCBand)
  {
    DestroyWindow (hwndCBand);
  }
  return NULL;
}

After you create a command bands control, you might want to add controls to the band or resize the band. Windows Embedded CE supports several functions for manipulating command bands.

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

To	Call
Add a band that contains the Close (X) button, the Help (?) button, and the OK button.	CommandBands_AddAdornments
Add one or more bands to the control. By default, each band has a command bar as its child window.	CommandBands_AddBands
Create a command bands control.	CommandBands_Create
Retrieve a command bar from a band in a command bands control. Pass the zero-based index of the band that contains the command bar that you want to retrieve.	CommandBands_GetCommandBar
Return the height of the command bands control.	CommandBands_Height
Retrieve the parent rectangle of the control.	GetClientRect
Determine whether a command bands control is visible.	CommandBands_IsVisible
Retrieve data about the bands in a command bands control so that you can save the data in the registry to restore the command bands control to a previous state.	CommandBands_GetRestoreInformation
Show or hide the command bands control.	CommandBands_Show

Because a command band is both a rebar control and a toolbar control, you also can manipulate the command band by using rebar messages and toolbar messages.

Command bands controls support the custom draw service, which makes it easy to customize the appearance of a command bands control.

See Also

Concepts

Working with Common Controls