Toolbar Control Reference

Toolbar Control Reference


This section contains information about the following new or updated API elements used with toolbar controls.

Toolbar Control and Button Styles

Toolbar Extended Styles

Toolbar Button States

Toolbar Standard Button Image Index Values

Functions
CreateMappedBitmap
CreateToolbarEx

Messages
TB_ADDBITMAP
TB_ADDBUTTONS
TB_ADDSTRING
TB_AUTOSIZE
TB_BUTTONCOUNT
TB_BUTTONSTRUCTSIZE
TB_CHANGEBITMAP
TB_CHECKBUTTON
TB_COMMANDTOINDEX
TB_CUSTOMIZE
TB_DELETEBUTTON
TB_ENABLEBUTTON
TB_GETANCHORHIGHLIGHT
TB_GETBITMAP
TB_GETBITMAPFLAGS
TB_GETBUTTON
TB_GETBUTTONINFO
TB_GETBUTTONSIZE
TB_GETBUTTONTEXT
TB_GETCOLORSCHEME
TB_GETDISABLEDIMAGELIST
TB_GETEXTENDEDSTYLE
TB_GETHOTIMAGELIST
TB_GETHOTITEM
TB_GETIMAGELIST
TB_GETINSERTMARK
TB_GETINSERTMARKCOLOR
TB_GETITEMRECT
TB_GETMAXSIZE
TB_GETOBJECT
TB_GETPADDING
TB_GETRECT
TB_GETROWS
TB_GETSTATE
TB_GETSTYLE
TB_GETTEXTROWS
TB_GETTOOLTIPS
TB_GETUNICODEFORMAT
TB_HIDEBUTTON
TB_HITTEST
TB_INDETERMINATE
TB_INSERTBUTTON
TB_INSERTMARKHITTEST
TB_ISBUTTONCHECKED
TB_ISBUTTONENABLED
TB_ISBUTTONHIDDEN
TB_ISBUTTONHIGHLIGHTED
TB_ISBUTTONINDETERMINATE
TB_ISBUTTONPRESSED
TB_LOADIMAGES
TB_MAPACCELERATOR
TB_MARKBUTTON
TB_MOVEBUTTON
TB_PRESSBUTTON
TB_REPLACEBITMAP
TB_SAVERESTORE
TB_SETANCHORHIGHLIGHT
TB_SETBITMAPSIZE
TB_SETBUTTONINFO
TB_SETBUTTONSIZE
TB_SETBUTTONWIDTH
TB_SETCMDID
TB_SETCOLORSCHEME
TB_SETDISABLEDIMAGELIST
TB_SETDRAWTEXTFLAGS
TB_SETEXTENDEDSTYLE
TB_SETHOTIMAGELIST
TB_SETHOTITEM
TB_SETIMAGELIST
TB_SETINDENT
TB_SETINSERTMARK
TB_SETINSERTMARKCOLOR
TB_SETMAXTEXTROWS
TB_SETPADDING
TB_SETPARENT
TB_SETROWS
TB_SETSTATE
TB_SETSTYLE
TB_SETTOOLTIPS
TB_SETUNICODEFORMAT

Notifications
NM_CHAR (toolbar)
NM_CUSTOMDRAW (toolbar)
NM_KEYDOWN (toolbar)
NM_RCLICK (toolbar)
NM_RDBLCLK (toolbar)
NM_RELEASEDCAPTURE (toolbar)
TBN_BEGINADJUST
TBN_BEGINDRAG
TBN_CUSTHELP
TBN_DELETINGBUTTON
TBN_DRAGOUT
TBN_DROPDOWN
TBN_ENDADJUST
TBN_ENDDRAG
TBN_GETBUTTONINFO
TBN_GETDISPINFO
TBN_GETOBJECT
TBN_HOTITEMCHANGE
TBN_QUERYDELETE
TBN_QUERYINSERT
TBN_RESET
TBN_TOOLBARCHANGE

Structures
COLORMAP
NMTBCUSTOMDRAW
NMTBDISPINFO
NMTBHOTITEM
NMTOOLBAR
TBADDBITMAP
TBBUTTON
TBBUTTONINFO
TBINSERTMARK
TBNOTIFY
TBREPLACEBITMAP
TBSAVEPARAMS

Toolbar Control Constants

This section contains information about the constants related to toolbar controls.

Toolbar Control and Button Styles

A toolbar control can have a combination of the following styles:

TBSTYLE_ALTDRAG Allows users to change a toolbar button's position by dragging it while holding down ALT. If this style is not specified, the user must hold down SHIFT while dragging a button. Note that the CCS_ADJUSTABLE style must be specified to enable toolbar buttons to be dragged.
TBSTYLE_CUSTOMERASE Version 4.70. Generates NM_CUSTOMDRAW notification messages when it processes WM_ERASEBKGND messages.
TBSTYLE_FLAT Version 4.70. Creates a flat toolbar. In a flat toolbar, both the toolbar and the buttons are transparent. Button text appears under button bitmaps. To prevent repainting problems, this style should be set before the toolbar control becomes visible.
TBSTYLE_LIST Version 4.70. Places button text to the right of button bitmaps. To prevent repainting problems, this style should be set before the toolbar control becomes visible.
TBSTYLE_REGISTERDROP Version 4.71. Generates TBN_GETOBJECT notification messages to request drop target objects when the pointer passes over toolbar buttons.
TBSTYLE_TOOLTIPS Creates a tooltip control that an application can use to display descriptive text for the buttons in the toolbar.
TBSTYLE_TRANSPARENT Version 4.71. Creates a transparent toolbar. In a transparent toolbar, the toolbar is transparent but the buttons are not. Button text appears under button bitmaps. To prevent repainting problems, this style should be set before the toolbar control becomes visible.
TBSTYLE_WRAPABLE Creates a toolbar that can have multiple lines of buttons. Toolbar buttons can "wrap" to the next line when the toolbar becomes too narrow to include all buttons on the same line. Wrapping occurs on separation and nongroup boundaries.

A button in a toolbar can have a combination of the following styles. Not all styles can be combined.
TBSTYLE_AUTOSIZE Version 4.71. The button's width will be calculated based on the text of the button, not on the size of the image.
TBSTYLE_BUTTON Creates a standard push button.
TBSTYLE_CHECK Creates a button that toggles between the pressed and nonpressed states each time the user clicks it. The button has a different background color when it is in the pressed state.
TBSTYLE_CHECKGROUP Creates a check button that stays pressed until another button in the group is pressed.
TBSTYLE_DROPDOWN Version 4.70. Creates a drop-down list button. Drop-down buttons send the TBN_DROPDOWN notification. If the toolbar has the TBSTYLE_EX_DRAWDDARROWS extended style, drop-down buttons will have a drop-down arrow displayed next to them.
TBSTYLE_GROUP Creates a button that stays pressed until another button in the group is pressed.
TBSTYLE_NOPREFIX Version 4.71. The button text will not have an accelerator prefix associated with it.
TBSTYLE_SEP Creates a separator, providing a small gap between button groups. A button that has this style does not receive user input.

Toolbar Extended Styles

A toolbar can have the following extended style. This style is set with the TB_SETEXTENDEDSTYLE message and retrieved with the TB_GETEXTENDEDSTYLE message.

TBSTYLE_EX_DRAWDDARROWS Version 4.71. Buttons that have the TBSTYLE_DROPDOWN style will be drawn with a drop-down arrow next to the button. If this extended style is not present, the drop-down buttons are drawn as normal buttons. To prevent repainting problems, this style should be set before the toolbar control becomes visible.

Toolbar Button States

A toolbar button can have a combination of the following states:

TBSTATE_CHECKED The button has the TBSTYLE_CHECK style and is being clicked.
TBSTATE_ELLIPSES Version 4.70. The button's text is cut off and an ellipsis is displayed.
TBSTATE_ENABLED The button accepts user input. A button that doesn't have this state is grayed.
TBSTATE_HIDDEN The button is not visible and cannot receive user input.
TBSTATE_INDETERMINATE The button is grayed.
TBSTATE_MARKED Version 4.71. The button is marked. The interpretation of a marked item is dependent upon the application.
TBSTATE_PRESSED The button is being clicked.
TBSTATE_WRAP The button is followed by a line break. The button must also have the TBSTATE_ENABLED state.

Toolbar Standard Button Image Index Values

The following values specify index values of images within standard bitmaps. Use these values to specify an image index within a standard image list that was loaded with the TB_LOADIMAGES message.

The following index values correspond to images within standard image lists that the control creates for your convenience. The images depict actions that Windows applications commonly perform.

Index values for IDB_HIST_LARGE_COLOR and IDB_HIST_SMALL_COLOR:
HIST_ADDTOFAVORITES Add to favorites.
HIST_BACK Move back.
HIST_FAVORITES Open favorites folder.
HIST_FORWARD Move forward.
HIST_VIEWTREE View tree.
Index values for IDB_STD_LARGE_COLOR and IDB_STD_SMALL_COLOR:
STD_COPY Copy operation.
STD_CUT Cut operation.
STD_DELETE Delete operation.
STD_FILENEW New file operation.
STD_FILEOPEN Open file operation.
STD_FILESAVE Save file operation.
STD_FIND Find operation.
STD_HELP Help operation.
STD_PASTE Paste operation.
STD_PRINT Print operation.
STD_PRINTPRE Print preview operation.
STD_PROPERTIES Properties operation.
STD_REDOW Redo operation.
STD_REPLACE Replace operation.
STD_UNDO Undo operation.
Index values for IDB_VIEW_LARGE_COLOR and IDB_VIEW_SMALL_COLOR:
VIEW_DETAILS Details view.
VIEW_LARGEICONS Large icons view.
VIEW_LIST List view.
VIEW_NETCONNECT Connect to network drive.
VIEW_NETDISCONNECT Disconnect from network drive.
VIEW_NEWFOLDER New folder.
VIEW_PARENTFOLDER Go to parent folder.
VIEW_SMALLICONS Small icon view.
VIEW_SORTDATE Sort by date.
VIEW_SORTNAME Sort by name.
VIEW_SORTSIZE Sort by size.
VIEW_SORTTYPE Sort by type.

Toolbar Control Functions

This section contains information about the functions used with toolbar controls.

CreateMappedBitmap

HBITMAP CreateMappedBitmap(
    HINSTANCE hInstance, 	
    int idBitmap, 	
    UINT wFlags, 	
    LPCOLORMAP lpColorMap, 	
    int iNumMaps	
);	

Creates a bitmap for use in a toolbar.

hInstance
Handle to the module instance with the executable file that contains the bitmap resource.
idBitmap
Resource identifier of the bitmap resource.
wFlags
Bitmap flag. This parameter can be zero or the following value:
CMB_MASKED Uses a bitmap as a mask.
lpColorMap
Address of a COLORMAP structure that contains the color information needed to map the bitmaps. If this parameter is NULL, the function uses the default color map.
iNumMaps
Number of color maps pointed to by lpColorMap.

The function creates a new bitmap using the bitmap data and colors specified by the bitmap resource and the color mapping information.

CreateToolbarEx

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	
);	

Creates a toolbar window and adds the specified buttons to the toolbar.

hwnd
Handle to the parent window for the toolbar.
ws
Window styles for the toolbar. This parameter must specify at least the WS_CHILD style. It can also include a combination of styles as discussed in Toolbar Control and Button Styles.
wID
Control identifier for the toolbar.
nBitmaps
Number of button images contained in the bitmap specified by hBMInst and wBMID.
hBMInst
Module instance with the executable file that contains the bitmap resource.
wBMID
Resource identifier for the bitmap resource. If hBMInst is NULL, this parameter must be a valid bitmap handle.
lpButtons
Address of an array of TBBUTTON structures that contain information about the buttons to add to the toolbar.
iNumButtons
Number of buttons to add to the toolbar.
dxButton
Width, in pixels, of the buttons to add to the toolbar.
dyButton
Height, in pixels, of the buttons to add to the toolbar.
dxBitmap
Width, in pixels, of the button images to add to the buttons in the toolbar.
dyBitmap
Height, in pixels, of the button images to add to the buttons in the toolbar.
uStructSize
Size of a TBBUTTON structure.

Windows 95: The system can support a maximum of 16,364 window handles.

Toolbar Control Messages

This section contains information about the messages used with toolbar controls.

TB_ADDBITMAP

TB_ADDBITMAP 
    wParam = (WPARAM) nButtons; 
    lParam = (LPARAM) (LPTBADDBITMAP) lptbab; 

Adds one or more images to the list of button images available for a toolbar.

nButtons
Number of button images in the bitmap. If lptbab specifies a system-defined bitmap, this parameter is ignored.
lptbab
Address of a TBADDBITMAP structure that contains the identifier of a bitmap resource and the handle to the module instance with the executable file that contains the bitmap resource.

If the toolbar was created using the CreateWindowEx function, you must send the TB_BUTTONSTRUCTSIZE message to the toolbar before sending TB_ADDBITMAP.

TB_ADDBUTTONS

TB_ADDBUTTONS 
    wParam = (WPARAM) (UINT) uNumButtons; 
    lParam = (LPARAM) (LPTBBUTTON) lpButtons; 

Adds one or more buttons to a toolbar.

uNumButtons
Number of buttons to add.
lpButtons
Address of an array of TBBUTTON structures that contain information about the buttons to add. There must be the same number of elements in the array as buttons specified by uNumButtons.

If the toolbar was created using the CreateWindowEx function, you must send the TB_BUTTONSTRUCTSIZE message to the toolbar before sending TB_ADDBUTTONS.

TB_ADDSTRING

TB_ADDSTRING 
    wParam = (WPARAM) (HINSTANCE) hinst; 
    lParam = (LPARAM) MAKELONG(idString, 0); 

Adds a new string to the list of strings available for a toolbar.

hinst
Handle to the module instance with an executable file that contains the string resource. If idString points to one or more strings to add, this parameter is zero.
idString
Resource identifier for the string resource, or the address of a buffer that contains one or more null-terminated strings to add to the list, depending on the value of hinst. The last string must be terminated with two null characters.

TB_AUTOSIZE

TB_AUTOSIZE 
    wParam = 0; 
    lParam = 0; 

Causes a toolbar to be resized.

An application sends the TB_AUTOSIZE message after causing the size of a toolbar to change either by setting the button or bitmap size or by adding strings for the first time.

TB_BUTTONCOUNT

TB_BUTTONCOUNT 
    wParam = 0; 
    lParam = 0; 

Retrieves a count of the buttons currently in the toolbar.

TB_BUTTONSTRUCTSIZE

TB_BUTTONSTRUCTSIZE
    wParam = (WPARAM) cb; 
    lParam = 0; 

Specifies the size of the TBBUTTON structure.

cb
Size, in bytes, of the TBBUTTON structure.

The system uses the size to determine which version of the common control dynamic-link library (DLL) is being used.

If an application uses the CreateWindowEx function to create the toolbar, the application must send this message to the toolbar before sending the TB_ADDBITMAP or TB_ADDBUTTONS message. The CreateToolbarEx function automatically sends TB_BUTTONSTRUCTSIZE, and the size of the TBBUTTON structure is a parameter of the function.

TB_CHANGEBITMAP

TB_CHANGEBITMAP 
    wParam = (WPARAM) idButton; 
    lParam = (LPARAM) MAKELPARAM(iBitmap, 0); 

Changes the bitmap for a button in a toolbar.

idButton
Command identifier of the button that is to receive a new bitmap.
iBitmap
Zero-based index of an image in the toolbar's image list. The system displays the specified image in the button.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.