Creating a Toolbar (Windows CE 5.0)

Article
09/14/2012

A toolbar is a control that contains buttons. The buttons in a toolbar usually correspond to items on the application menu, and provide 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 that contains the command identifier of the button.

Each button in a toolbar can include a bitmap image. A toolbar maintains an internal list that contains all of the bitmaps that are 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 that is added to the internal list has an index of zero, the second image has an index of one, and so on. The TB_ADDBITMAP message adds images to the end of the list and returns the index of the first new image that it has added. You use an image index to associate the image with a button.

Windows CE assumes that all toolbar bitmaps are of the same size. You specify the size when you create the toolbar by calling the CreateToolbarEx function. 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 you add 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 that are available to toolbar buttons. You add strings to the internal list by using the TB_ADDSTRING message and by specifying the address of the buffer that contains the strings that you want 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 that is added to the internal list of strings has an index of zero, the second string has an index of one, and so on. The TB_ADDSTRING message adds strings to the end of the list and returns the index of the first new string. You use the index of a string 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 the initial state of a button when you add the button to the toolbar, and the toolbar updates the state of the button in response to the actions of the user; for example, when a user taps it with a stylus. You can use the TB_GETSTATE and TB_SETSTATE messages, respectively, to retrieve and set the state of a button.

The following table shows toolbar button states that Windows CE supports.

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 that follows it. The button also must have the TBSTATE_ENABLED state.

To create a toolbar

Use the CreateToolbarEx function, which uses 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. At a minimum, a toolbar must include the WS_CHILD style. You also can 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 message or a 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 that is associated with the toolbar is specified in wID. The nBitmaps parameter specifies the number of button images that are contained in the bitmap that is specified by hBMInst and wBMID.

Button data is contained in an array of structures that is named TBBUTTON; lpButtons is the address of this array. Specific button data — such as the number of buttons to add to the toolbar, button width and height, and the width and height of button images — is specified in iNumButtons, dxButton and dyButton, and 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;              // Height of the command bar 
  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; // The INITCOMMONCONTROLSEX structure
  
  iccex.dwSize = sizeof (INITCOMMONCONTROLSEX);
  iccex.dwICC = ICC_BAR_CLASSES;

  // Register toolbar control classes from the DLL for the common 
  // control.
  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 also can call the CreateWindowEx function to create a toolbar. By using this method, however, you create a toolbar that initially contains no buttons. You can add buttons to the toolbar by using the TB_ADDBUTTONS message or the TB_INSERTBUTTON message. If you use the CreateWindowEx function to create the toolbar, the application must send a TB_BUTTONSTRUCTSIZE message to the toolbar before sending a 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 DLL for the common control DLL. You can call the InitCommonControls function to ensure that this DLL is loaded. When you register the toolbar class by calling the InitCommonControlsEx function, specify the ICC_BAR_CLASSES flag as the dwICC member of the INITCOMMONCONTROLSEX structure that 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 you create the toolbar, but you can change the parent window after you create the toolbar by using the TB_SETPARENT message.

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

See Also

Additional resources