Sets the image list that the toolbar uses to display buttons that are in their default state.



Version 5.80. The index of the list. If you use only one image list, or an earlier version of the common controls, set wParam to zero. See Remarks for details on using multiple image lists.


Handle to the image list to set. If this parameter is NULL, no images are displayed in the buttons.

Return value

Returns the handle to the image list previously used to display buttons in their default state, or NULL if no image list was previously set.



Your application is responsible for freeing the image list after the toolbar is destroyed.

The TB_SETIMAGELIST message cannot be combined with TB_ADDBITMAP. It also cannot be used with toolbars created with CreateToolbarEx, which calls TB_ADDBITMAP internally. When you create a toolbar with CreateToolbarEx or use TB_ADDBITMAP to add images, the toolbar manages the image list internally. Attempting to modify it with TB_SETIMAGELIST has unpredictable consequences.

With version 5.80 or later of the common controls, button images need not come from the same image list. To use multiple image lists for your toolbar button images:

  1. Enable multiple image lists by sending the toolbar control a CCM_SETVERSION message with wParam (the version number) set to 5.
  2. For each image list you want to use, send the toolbar control a TB_SETIMAGELIST message. Set wParam to an application-defined wParam value that will be used to identify the list. Set lParam to the list's HIMAGELIST handle.
  3. For each button, set the iBitmap member of the button's TBBUTTON structure to MAKELONG(iIndex, iImageID). The iImageID value is the ID of the appropriate image list that was defined in step two. The iIndex value is the index of the particular image within that list.
  4. Add the buttons by sending the toolbar control a TB_ADDBUTTONS message.

The following code fragment illustrates how to add five buttons to a toolbar, with images from three different image lists. Support for multiple image lists is enabled with a CCM_SETVERSION message. The image lists are then set and assigned IDs of 0-2. The buttons are assigned images from the image lists as follows:

  • Button 0 is from image list zero (ahim[0]) with index of 1.
  • Button 1 is from image list one (ahim[1]) with an index of 1.
  • Button 2 is from image list two (ahim[2]) with an index of 1.
  • Button 3 is from image list zero (ahim[0]) with an index of 2.
  • Button 4 is from image list one (ahim[1]) with an index of 3.

Finally, the buttons are added to the toolbar control with a TB_ADDBUTTONS message.

//Enable multiple image lists
    SendMessage(hwndTB, CCM_SETVERSION, (WPARAM) 5, 0); 

    //Set the image lists and assign them IDs of 0-2
    SendMessage(hwndTB, TB_SETIMAGELIST, 0, (LPARAM)ahiml[0]);
    SendMessage(hwndTB, TB_SETIMAGELIST, 1, (LPARAM)ahiml[1]);
    SendMessage(hwndTB, TB_SETIMAGELIST, 2, (LPARAM)ahiml[2]);

    // Create the five buttons
    TBBUTTON rgtb[5];
    //... initialize the TBBUTTON structures as usual ...
    //Assign images to each button
    rgtb[0].iBitmap = MAKELONG(1, 0);
    rgtb[1].iBitmap = MAKELONG(1, 1);
    rgtb[2].iBitmap = MAKELONG(1, 2);
    rgtb[3].iBitmap = MAKELONG(2, 0);
    rgtb[4].iBitmap = MAKELONG(3, 1);

    // Add the five buttons to the toolbar control
    SendMessage(hwndTB, TB_ADDBUTTONS, 5, (LPARAM)(&rgtb);


Requirement Value
Minimum supported client
Windows Vista [desktop apps only]
Minimum supported server
Windows Server 2003 [desktop apps only]

See also