Toolbar Control and Button Styles
The following window styles are specific to toolbars. They are combined with other window styles when the toolbar is created.
Note For Common Controls version 6.00, if a visual style is being used with the toolbar, buttons are always transparent regardless of the style setting. Otherwise, transparency behavior is normal as indicated by the use of the TBSTYLE_FLAT or TBSTYLE_TRANSPARENT style.
Comctl32.dll version 6 is not redistributable but it is included in Windows. To use Comctl32.dll version 6, specify it in a manifest. For more information on manifests, see Enabling Visual Styles.
| Constant | Description |
|---|---|
| TBSTYLE_ALTDRAG | Allows users to change a toolbar button’s position by dragging it while holding down the ALT key. If this style is not specified, the user must hold down the SHIFT key 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 codes when the toolbar 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 and hot-tracking is enabled. 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. Creates a flat toolbar with button text to the right of the bitmap. Otherwise, this style is identical to TBSTYLE_FLAT. To prevent repainting problems, this style should be set before the toolbar control becomes visible. |
| TBSTYLE_REGISTERDROP | Version 4.71. Generates TBN_GETOBJECT notification codes to request drop target objects when the cursor 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. When the toolbar is wrapped, the break will occur on either the rightmost separator or the rightmost button if there are no separators on the bar. This style must be set to display a vertical toolbar control when the toolbar is part of a vertical rebar control. This style cannot be combined with CCS_VERT. |
Note: A toolbar button can have a combination of the following styles. To specify a button style, set the appropriate flags in the fsStyle member of the button’s TBBUTTON structure. Not all styles can be combined.
Button Messages
A button can send messages to its parent window, and a parent window can send messages to a button.
The following topics are discussed in this section.
Sending Messages to Buttons
A parent window can send messages to a button in an overlapped or child window by using the SendMessage function, or it can send messages to a button in a dialog box by using the SendDlgItemMessage, CheckDlgButton, CheckRadioButton, and IsDlgButtonChecked functions.
An application can use the BM_GETCHECK message to retrieve the check state of a check box or radio button. An application can also use the BM_GETSTATE message to retrieve the button’s current states (the check state, push state, and focus state). To get information about a specific state, use a bitmask on the returned state value.
The BM_SETCHECK message sets the check state of a check box or radio button; the message returns zero. The BM_SETSTATE message sets the push state of a button; this message also returns zero. The BM_SETSTYLE message changes the style of a button. It is designed for changing button styles within a type (for example, changing a check box to an automatic check box). It is not designed for changing between types (for example, changing a check box to a radio button). An application should not change a button from one type to another.
A button of the BS_BITMAP or BS_ICON style displays a bitmap or icon instead of text. The BM_SETIMAGE message associates a handle to a bitmap or icon with a button. The BM_GETIMAGE message retrieves a handle to the bitmap or icon associated with a button.
An application can also use the DM_GETDEFID message to retrieve the identifier of the default push button control in a dialog box. An application can use the DM_SETDEFID message to set the default push button for a dialog box.
Handling Messages from a Button
Notifications from a button are sent as either WM_COMMAND or WM_NOTIFY messages. Information about which message is used can be found on the reference page for each notification.
For more information on how to handle messages, see Control Messages. See also Button Messages.
Notification Messages from Buttons
When the user clicks a button, its state changes, and the button sends notification codes, in the form of WM_COMMAND messages, to its parent window. For example, a push button control sends the BN_CLICKED notification code whenever the user chooses the button. In all cases (except for BCN_HOTITEMCHANGE), the low-order word of the wParam parameter contains the control identifier, the high-order word of wParam contains the notification code, and the lParam parameter contains the control window handle.
Both the message and the parent window’s response depend on the type, style, and current state of the button. Following are the button notification codes an application should monitor and process.
| Notification code | Description |
|---|---|
| BCN_HOTITEMCHANGE | The mouse entered or left the client area of a button. |
| BN_CLICKED | The user clicked a button. |
| BN_DBLCLK or BN_DOUBLECLICKED | The user double-clicked a button. |
| BN_DISABLE | A button is disabled. |
| BN_PUSHED or BN_HILITE | The user pushed a button. |
| BN_KILLFOCUS | The button lost the keyboard focus. |
| BN_PAINT | The button should be painted. |
| BN_SETFOCUS | The button gained the keyboard focus. |
| BN_UNPUSHED or BN_UNHILITE | The button is no longer pushed. |
A button sends the BN_DISABLE, BN_PUSHED, BN_KILLFOCUS, BN_PAINT, BN_SETFOCUS, and BN_UNPUSHED notification codes only if it has the BS_NOTIFY style. BN_DBLCLK notification codes are sent automatically for BS_USERBUTTON, BS_RADIOBUTTON, and BS_OWNERDRAW buttons. Other button types send BN_DBLCLK only if they have the BS_NOTIFY style. All buttons send the BN_CLICKED notification code regardless of their button styles.
For automatic buttons, the system changes the push state and paints the button. In this case, the application typically processes only the BN_CLICKED and BN_DBLCLK notification codes. For buttons that are not automatic, the application typically responds to the notification code by sending a message to change the state of the button. For information about sending messages to buttons, see Sending Messages to Buttons.
When the user selects an owner-drawn button, the button sends its parent window a WM_DRAWITEM message containing the identifier of the control to be drawn and information about its dimensions and state.
Button Color Messages
The system provides default color values for buttons. An application can retrieve the default values for these colors by calling the GetSysColor function, or set the values by calling the SetSysColors function. The following table shows the default button-color values.
| Value | Element colored |
|---|---|
| COLOR_BTNFACE | Button faces. |
| COLOR_BTNHIGHLIGHT | Highlight area (the top and left edges) of a button. |
| COLOR_BTNSHADOW | Shadow area (the bottom and right edges) of a button. |
| COLOR_BTNTEXT | Regular (nongrayed) text in buttons. |
| COLOR_GRAYTEXT | Disabled (gray) text in buttons. This color is set to 0 if the current display driver does not support a solid gray color. |
| COLOR_WINDOW | Window backgrounds. |
| COLOR_WINDOWFRAME | Window frames. |
| COLOR_WINDOWTEXT | Text in windows. |
However, calling SetSysColors affects all applications, so you should not call this function to customize buttons for your application.
The system sends a WM_CTLCOLORBTN message to a button’s parent window before drawing a button. This message contains a handle to the button’s device context and a handle to the child window. The parent window can use these handles to change the button’s text and background colors. However, only owner-drawn buttons respond to the parent window processing the message.
Button Default Message Processing
The window procedure for the predefined button control window class carries out default processing for all messages that the button control procedure does not process. When the button control procedure returns FALSE for any message, the predefined window procedure checks the messages and performs the default actions listed in the following table.
| Message | Default action | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| BM_CLICK | Sends the button a WM_LBUTTONDOWN and a WM_LBUTTONUP message, and sends the parent window a BN_CLICKED notification code. | ||||||||||||||||
| BM_GETCHECK | Returns the check state of the button. | ||||||||||||||||
| BM_GETIMAGE | Returns a handle to the bitmap or icon associated with the button or NULL if the button has no bitmap or icon. | ||||||||||||||||
| BM_GETSTATE | Returns the current check state, push state, and focus state of the button. | ||||||||||||||||
| BM_SETCHECK | Sets the check state for all styles of radio buttons and check boxes. If the wParam parameter is greater than zero for radio buttons, the button is given the WS_TABSTOP style. | ||||||||||||||||
| BM_SETIMAGE | Associates the specified bitmap or icon handle with the button and returns a handle to the previous bitmap or icon. | ||||||||||||||||
| BM_SETSTATE | Sets the push state of the button. For owner-drawn buttons, a WM_DRAWITEM message is sent to the parent window if the state of the button has changed. | ||||||||||||||||
| BM_SETSTYLE | Sets the button style. If the low-order word of the lParam parameter is TRUE, the button is redrawn. | ||||||||||||||||
| WM_CHAR | Checks a check box or automatic check box when the user presses the plus (+) or equal (=) keys. Clears a check box or automatic check box when the user presses the minus (–) key. | ||||||||||||||||
| WM_ENABLE | Paints the button. | ||||||||||||||||
| WM_ERASEBKGND | Erases the background for owner-drawn buttons. The backgrounds of other buttons are erased as part of the WM_PAINT and WM_ENABLE processing. | ||||||||||||||||
| WM_GETDLGCODE | Returns values that indicate the type of input processed by the default button procedure, as shown in the following table.
| ||||||||||||||||
| WM_GETFONT | Returns a handle to the current font. | ||||||||||||||||
| WM_KEYDOWN | Pushes the button if the user presses the SPACEBAR. | ||||||||||||||||
| WM_KEYUP | Releases the mouse capture for all cases except the TAB key. | ||||||||||||||||
| WM_KILLFOCUS | Removes the focus rectangle from a button. For push buttons and default push buttons, the focus rectangle is invalidated. If the button has the mouse capture, the capture is released, the button is not clicked, and any push state is removed. | ||||||||||||||||
| WM_LBUTTONDBLCLK | Sends a BN_DBLCLK notification code to the parent window for radio buttons and owner-drawn buttons. For other buttons, a double-click is processed as a WM_LBUTTONDOWN message. | ||||||||||||||||
| WM_LBUTTONDOWN | Highlights the button if the position of the mouse cursor is within the button’s client rectangle. | ||||||||||||||||
| WM_LBUTTONUP | Releases the mouse capture if the button had the mouse capture. | ||||||||||||||||
| WM_MOUSEMOVE | Performs the same action as WM_LBUTTONDOWN, if the button has the mouse capture. Otherwise, no action is performed. | ||||||||||||||||
| WM_NCCREATE | Turns any BS_OWNERDRAW button into a BS_PUSHBUTTON button. | ||||||||||||||||
| WM_NCHITTEST | Returns HTTRANSPARENT, if the button control is a group box. | ||||||||||||||||
| WM_PAINT | Draws the button according to its style and current state. | ||||||||||||||||
| WM_SETFOCUS | Draws a focus rectangle on the button getting the focus. For radio buttons and automatic radio buttons, the parent window is sent a BN_CLICKED notification code. | ||||||||||||||||
| WM_SETFONT | Sets a new font and optionally updates the window. | ||||||||||||||||
| WM_SETTEXT | Sets the text of the button. In the case of a group box, the message paints over the preexisting text before repainting the group box with the new text. | ||||||||||||||||
| WM_SYSKEYUP | Releases the mouse capture for all cases except the TAB key. |
The predefined window procedure passes all other messages to the DefWindowProc function for default processing.
