Creating a Toolbar

A toolbar is a control that contains buttons. The buttons in a toolbar usually correspond to items on the application menu, providing a quick way for a user to access these commands. Toolbar buttons are bit images, and not child windows as are other buttons. When a user taps a toolbar button, the toolbar sends its parent window a WM_COMMAND message with the button's command identifier.

Each button in a toolbar can include a bitmap image. A toolbar maintains an internal list that contains all of the bitmaps assigned to each of its toolbar buttons. When you call the CreateToolbarEx function, you specify a monochrome or color bitmap that contains the initial images. The toolbar then adds the information to the internal list of images. You can add additional images later by using the TB_ADDBITMAP message.

Each image has a zero-based index. The first image added to the internal list has an index of zero, the second image has an index of one, and so on. TB_ADDBITMAP adds images to the end of the list and returns the index of the first new image that it added. You use an image index to associate the image with a button.

Windows CE assumes that all toolbar bitmaps are the same size. You specify the size when you create the toolbar by calling CreateToolbarEx. If you call the CreateWindowEx function to create a toolbar, the size of its bitmaps is set to the default dimensions of 16 x 15 pixels. You can use the TB_SETBITMAPSIZE message to change the dimensions of the bitmaps, but you must do so before adding any images to the internal list of images.

Each button can display a string in addition to, or instead of, an image. A toolbar maintains an internal list that contains all of the strings available to toolbar buttons. You add strings to the internal list by using the TB_ADDSTRING message, specifying the address of the buffer containing the strings to add. Each string must be null-terminated, and the last string must be terminated with two null characters.

Each string has a zero-based index. The first string added to the internal list of strings has an index of zero, the second string has an index of one, and so on. TB_ADDSTRING adds strings to the end of the list and returns the index of the first new string. You use a string's index to associate the string with a button.

Each button in a toolbar has a current state that indicates whether the button is hidden or visible, enabled or disabled, and pressed or not pressed. You set a button's initial state when adding the button to the toolbar, and the toolbar updates the button state in response to a user's actions, for example, when a user taps it with a stylus. You can use the TB_GETSTATE and TB_SETSTATE messages to retrieve and set the state of a button.

The following table shows toolbar button states supported by Windows CE.

State	Description
TBSTATE_CHECKED	The button has the TBSTYLE_CHECKED style and is pressed.
TBSTATE_ELLIPSES	The button displays ellipses if the text does not fit the size of the button. This style is unique to Windows CE.
TBSTATE_ENABLED	The button accepts user input. A button without this state does not accept user input and is dimmed.
TBSTATE_HIDDEN	The button is not visible and cannot receive user input.
TBSTATE_HIGHLIGHTED	The button is highlighted.
TBSTATE_INDETERMINATE	The button is dimmed.
TBSTATE_PRESSED	The button is being pressed.
TBSTATE_WRAP	The button has a line break following it. The button must also have the TBSTATE_ENABLED state.

To create a toolbar

Use the CreateToolbarEx function, which has the following syntax:
```
HWND CreateToolbarEx(
    HWND hwnd,    
    DWORD ws,    
    UINT wID,     
    int nBitmaps,     
    HINSTANCE hBMInst, 
    UINT wBMID,     
    LPCTBBUTTON lpButtons, 
    int iNumButtons,     
    int dxButton,     
    int dyButton,     
    int dxBitmap,     
    int dyBitmap,     
    UINT uStructSize    
);    
```
Here, hwnd is the handle to the parent window that owns the toolbar and ws is the style of the toolbar. Minimally, a toolbar must include the WS_CHILD style. You can also specify other styles. For example, in Windows CE the TBSTYLE_LIST style creates a toolbar with variable-width buttons. If you want to use the TBSTYLE_LIST style with fixed-width buttons, you can override the default behavior by sending a TB_SETBUTTONSIZE or TB_SETBUTTONWIDTH message. To keep a toolbar from automatically aligning to the top or bottom of a parent window, specify the CCS_NOPARENTALIGN style. For a complete listing of supported styles, see Window and Control Styles.
The identifier associated with the toolbar is specified in wID and the number of button images contained in the bitmap specified by hBMInst and wBMID is specified in nBitmaps.
Button data is contained in an array of structures called TBBUTTON; lpButtons is the address of this array. Specific button data, such as the number of buttons to add to the toolbar, button height and width, and the height and width of button images, are specified in iNumButtons, dxButton, dyButton, dxBitmap, and dyBitmap, respectively. The size of the TBBUTTON structure is specified in uStructSize. The following screen shot shows a Windows CE toolbar.

The following code example shows how to create and register a toolbar.

HWND WINAPI CreateToolbar (HWND hwnd)
{
  int iCBHeight;              // Command bar height 
  DWORD dwStyle;              // Style of the toolbar
  HWND hwndTB = NULL;         // Handle to the command bar control 
  RECT rect,                  // Contains the coordinates of the main 
                              // window client area         
       rectTB;                // Contains the dimensions of the bounding
                              // rectangle of the toolbar control
  INITCOMMONCONTROLSEX iccex; // INITCOMMONCONTROLSEX structure
  
  iccex.dwSize = sizeof (INITCOMMONCONTROLSEX);
  iccex.dwICC = ICC_BAR_CLASSES;

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

  // Create the toolbar control.
  dwStyle = WS_VISIBLE | WS_CHILD | TBSTYLE_TOOLTIPS | 
            CCS_NOPARENTALIGN;
  
  if (!(hwndTB = CreateToolbarEx (
                  hwnd,               // Parent window handle
                  dwStyle,            // Toolbar window styles
                  (UINT) ID_TOOLBAR,  // Toolbar control identifier
                  NUMIMAGES,          // Number of button images
                  hInst,              // Module instance 
                  IDB_TOOLBAR,        // Bitmap resource identifier
                  tbButton,           // Array of TBBUTTON structure 
                                      // contains button data
                  sizeof (tbButton) / sizeof (TBBUTTON),
                                      // Number of buttons in toolbar
                  BUTTONWIDTH,        // Width of the button in pixels
                  BUTTONHEIGHT,       // Height of the button in pixels
                  IMAGEWIDTH,         // Button image width in pixels
                  IMAGEHEIGHT,        // Button image height in pixels
                  sizeof (TBBUTTON))))// Size of a TBBUTTON structure
  {
    return NULL;
  }
  
  // Add ToolTips to the toolbar.
  SendMessage (hwndTB, TB_SETTOOLTIPS, (WPARAM) NUMIMAGES, 
               (LPARAM) szToolTips);

  // Reposition the toolbar.
  GetClientRect (hwnd, &rect);
  GetWindowRect (hwndTB, &rectTB);
  iCBHeight = CommandBar_Height (hwndCB);
  MoveWindow (hwndTB, 
              0, 
              iCBHeight - 2, 
              rect.right - rect.left, 
              rectTB.bottom - rectTB.top,
              TRUE);

  return hwndTB;
}

You can also call the CreateWindowEx function to create a toolbar. Using this method, however, creates a toolbar that initially contains no buttons. You can then add buttons to the toolbar by using the TB_ADDBUTTONS or TB_INSERTBUTTON message. You register the toolbar class by specifying the TOOLBARCLASSNAME window class. Windows CE registers the TOOLBARCLASSNAME class when it loads the common control DLL. You can call the InitCommonControls function to ensure that this DLL is loaded. To register the toolbar class using the InitCommonControlsEx function, specify the ICC_BAR_CLASSES flag as the dwICC member of the INITCOMMONCONTROLSEX structure you pass in the lpInitCtrls parameter.

If you use CreateWindowEx to create a toolbar, you must specify the WS_CHILD window style. CreateToolbarEx includes the WS_CHILD style by default. You must specify the initial parent window when creating the toolbar, but you can change the parent window after creation by using the TB_SETPARENT message.

Windows CE does not support user customization of toolbars or drag-and-drop operations for toolbars.

Creating a Toolbar

State

Description

To create a toolbar