Edit

Button Messages

  • Article

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.

Calling the CheckDlgButton or CheckRadioButton function is equivalent to sending a BM_SETCHECK message. Calling the IsDlgButtonChecked function is equivalent to sending a BM_GETCHECK message.

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.
Button style Returns
BS_AUTOCHECKBOX DLGC_WANTCHARS | DLGC_BUTTON
BS_AUTORADIOBUTTON DLGC_RADIOBUTTON | DLGC_BUTTON
BS_CHECKBOX DLGC_WANTCHARS | DLGC_BUTTON
BS_DEFPUSHBUTTON DLGC_DEFPUSHBUTTON | DLGC_BUTTON
BS_GROUPBOX DLGC_STATIC
BS_PUSHBUTTON DLGC_UNDEFPUSHBUTTON | DLGC_BUTTON
BS_RADIOBUTTON DLGC_RADIOBUTTON | DLGC_BUTTON

 
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.

Control Messages