Creating a Command Bands Control

The command bands control is a special kind of rebar control. It has a fixed band at the top containing 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, however, if you want a band to contain some other type of child window. The following screen shot shows a Windows CE command band.

    To create a command bands control

1. Initialize an INITCOMMONCONTROLSEX structure with (ICC_BAR_CLASSES | ICC_COOL_CLASSES) as the dwICC member.
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 then passing 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, passing 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 you want to add.
8. Call the CommandBands_AddAdornments function to add the Close and Help buttons. When you do this, 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
       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 the common control
  // DLL. 
  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)))
    return NULL;

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

  // 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))
    return NULL;

  // 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;
}

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

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

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

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