Button Messages
The following messages are used with buttons.
BM_CLICK
An application sends a BM_CLICK message to simulate the user clicking a button. This message causes the button to receive the WM_LBUTTONDOWN and WM_LBUTTONUP messages, and the button's parent window to receive a BN_CLICKED notification message.
To send this message, call the SendMessage function with the following parameters.
SendMessage(
(HWND) hWnd, // handle to destination window
BM_CLICK, // message to send
(WPARAM) wParam; // not used; must be zero
(LPARAM) lParam; // not used; must be zero
);
Parameters
This message has no parameters.
Return Values
This message does not return a value.
Remarks
If the button is in a dialog box and the dialog box is not active, the BM_CLICK message might fail. To ensure success in this situation, call the SetActiveWindow function to activate the dialog box before sending the BM_CLICK message to the button.
BM_GETCHECK
An application sends a BM_GETCHECK message to retrieve the check state of a radio button or check box.
To send this message, call the SendMessage function with the following parameters.
SendMessage(
(HWND) hWnd, // handle to destination window
BM_GETCHECK, // message to send
(WPARAM) wParam; // not used; must be zero
(LPARAM) lParam; // not used; must be zero
);
Parameters
This message has no parameters.
Return Values
The return value from a button created with the BS_AUTOCHECKBOX, BS_AUTORADIOBUTTON, BS_AUTO3STATE, BS_CHECKBOX, BS_RADIOBUTTON, or BS_3STATE style can be one of the following.
Value
Meaning

BST_CHECKED
Button is checked.

BST_INDETERMINATE
Button is grayed, indicating an indeterminate state (applies only if the button has the BS_3STATE or BS_AUTO3STATE style).

BST_UNCHECKED
Button is cleared

If the button has any other style, the return value is zero.
BM_GETIMAGE
An application sends a BM_GETIMAGE message to retrieve a handle to the image (icon or bitmap) associated with the button.
To send this message, call the SendMessage function with the following parameters.
SendMessage(
(HWND) hWnd, // handle to destination window
BM_GETIMAGE, // message to send
(WPARAM) ; // image type
(LPARAM) ; // not used; must be zero
);
Parameters
wParam
Specifies the type of image to associate with the button. This parameter can be one of the following values:
IMAGE_BITMAPIMAGE_ICON
lParam
This parameter is not used.
Return Values
The return value is a handle to the image, if any; otherwise, it is NULL.
BM_GETSTATE
An application sends a BM_GETSTATE message to determine the state of a button or check box.
To send this message, call the SendMessage function with the following parameters.
SendMessage(
(HWND) hWnd, // handle to destination window
BM_GETSTATE, // message to send
(WPARAM) wParam; // not used; must be zero
(LPARAM) lParam; // not used; must be zero
);
Parameters
This message has no parameters.
Return Values
The return value specifies the current state of the button. You can use the following values to extract information about the state.
Value
Meaning

0x0003
Specifies the check state (radio buttons and check boxes only). A value of BST_UNCHECKED indicates the button is cleared; a value of BST_CHECKED indicates the button is checked. A radio button is checked when it contains a dot; a check box is checked when it contains an X. A value of BST_INDETERMINATE indicates the check state is indeterminate (applies only if the button has the BS_3STATE or BS_AUTO3STATE style). A three-state check box is grayed when its state is indeterminate.

BST_CHECKED
Indicates the button is checked.

BST_FOCUS
Specifies the focus state. A nonzero value indicates that the button has the keyboard focus.

BST_INDETERMINATE
Indicates the button is grayed because the state of the button is indeterminate. This value applies only if the button has the BS_3STATE or BS_AUTO3STATE style.

BST_PUSHED
Specifies the highlight state. A nonzero value indicates that the button is highlighted. A button is automatically highlighted when the user positions the cursor over it and presses and holds the left mouse button. The highlighting is removed when the user releases the mouse button.

BST_UNCHECKED
Indicates the button is cleared. Same as a return value of zero.


BM_SETCHECK
An application sends a BM_SETCHECK message to set the check state of a radio button or check box.
To send this message, call the SendMessage function with the following parameters.
SendMessage(
(HWND) hWnd, // handle to destination window
BM_SETCHECK, // message to send
(WPARAM) ; // check state
(LPARAM) ; // not used; must be zero
);
Parameters
wParam
Specifies the check state. This parameter can be one of the following values.
Value
Meaning

BST_CHECKED
Sets the button state to checked.

BST_INDETERMINATE
Sets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style.

BST_UNCHECKED
Sets the button state to cleared.

lParam
This parameter is not used.
Return Values
This message always returns zero.
Remarks
The BM_SETCHECK message has no effect on push buttons.
BM_SETIMAGE
An application sends a BM_SETIMAGE message to associate a new image (icon or bitmap) with the button.
To send this message, call the SendMessage function with the following parameters.
SendMessage(
(HWND) hWnd, // handle to destination window
BM_SETIMAGE, // message to send
(WPARAM) ; // image type
(LPARAM) ; // handle to the image (HANDLE)
);
Parameters
wParam
Specifies the type of image to associate with the button. This parameter can be one of the following values:
IMAGE_BITMAPIMAGE_ICON
lParam
Handle to the image to associate with the button.
Return Values
The return value is a handle to the image previously associated with the button, if any; otherwise, it is NULL.
BM_SETSTATE
An application sends a BM_SETSTATE message to change the highlight state of a button. The highlight state indicates whether the button is highlighted as if the user had pushed it.
To send this message, call the SendMessage function with the following parameters.
SendMessage(
(HWND) hWnd, // handle to destination window
BM_SETSTATE, // message to send
(WPARAM) ; // highlight state
(LPARAM) ; // not used; must be zero
);
Parameters
wParam
Specifies whether the button is to be highlighted. A value of TRUE highlights the button. A value of FALSE removes any highlighting.
lParam
This parameter is not used.
Return Values
This message always returns zero.
Remarks
Highlighting only affects the appearance of a button. It has no effect on the check state of a radio button or check box.
A button is automatically highlighted when the user positions the cursor over it and presses and holds the left mouse button. The highlighting is removed when the user releases the mouse button.
BM_SETSTYLE
An application sends a BM_SETSTYLE message to change the style of a button.
To send this message, call the SendMessage function with the following parameters.
SendMessage(
(HWND) hWnd, // handle to destination window
BM_SETSTYLE, // message to send
(WPARAM) ; // button style
(LPARAM) ; // redraw state
);
Parameters
wParam
Specifies the new button style. This parameter can be a combination of button styles. For a table of button styles, see Button Styles.
lParam
The low-order word of lParam specifies whether the button is to be redrawn. A value of TRUE redraws the button; a value of FALSE does not redraw the button.
Return Values
This message always returns zero.
BN_CLICKED
The BN_CLICKED notification code is sent when the user clicks a button.
The parent window of the button receives the BN_CLICKED notification code through the WM_COMMAND message.
LRESULT CALLBACK WindowProc(
HWND hwnd, // handle to window
UINT uMsg, // WM_COMMAND
WPARAM // identifier of button, BN_CLICKED
LPARAM // handle to button (HWND)
);
Parameters
wParam
The low-order word contains the button's control identifier.
The high-order word specifies the notification message.
lParam
Handle to the button.
Remarks
A disabled button does not send a BN_CLICKED notification message to its parent window.
BN_DBLCLK
The BN_DBLCLK notification code is sent when the user double-clicks a button. This notification is 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.
The parent window of the button receives the BN_DBLCLK notification code through the WM_COMMAND message.
LRESULT CALLBACK WindowProc(
HWND hwnd, // handle to window
UINT uMsg, // WM_COMMAND
WPARAM // identifier of button, BN_DBLCLK
LPARAM // handle to button (HWND)
);
Parameters
wParam
The low-order word contains the button's control identifier.
The high-order word specifies the notification message.
lParam
Handle to the button.
Remarks
BN_DBLCLK is the same as the BN_DOUBLECLICKED notification message.
BN_DOUBLECLICKED
The BN_DOUBLECLICKED notification code is sent when the user double-clicks a button. This notification is sent automatically for BS_USERBUTTON, BS_RADIOBUTTON, and BS_OWNERDRAW buttons. Other button types send BN_DOUBLECLICKED only if they have the BS_NOTIFY style.
The parent window of the button receives the BN_DOUBLECLICKED notification code through the WM_COMMAND message.
LRESULT CALLBACK WindowProc(
HWND hwnd, // handle to window
UINT uMsg, // WM_COMMAND
WPARAM // identifier of button, BN_DOUBLECLICKED
LPARAM // handle to button (HWND)
);
Parameters
wParam
The low-order word contains the button's control identifier.
The high-order word specifies the notification message.
lParam
Handle to the button.
Remarks
BN_DOUBLECLICKED is the same as the BN_DBLCLK notification message.
BN_KILLFOCUS
The BN_KILLFOCUS notification code is sent when a button loses the keyboard focus. The button must have the BS_NOTIFY style to send this notification message.
The parent window of the button receives the BN_KILLFOCUS notification code through the WM_COMMAND message.
LRESULT CALLBACK WindowProc(
HWND hwnd, // handle to window
UINT uMsg, // WM_COMMAND
WPARAM // identifier of button, BN_KILLFOCUS
LPARAM // handle to button (HWND)
);
Parameters
wParam
The low-order word contains the button's control identifier.
The high-order word specifies the notification message.
lParam
Handle to the button.
BN_SETFOCUS
The BN_SETFOCUS notification code is sent when a button receives the keyboard focus. The button must have the BS_NOTIFY style to send this notification message.
The parent window of the button receives the BN_SETFOCUS notification code through the WM_COMMAND message.
LRESULT CALLBACK WindowProc(
HWND hwnd, // handle to window
UINT uMsg, // WM_COMMAND
WPARAM // identifier of button, BN_SETFOCUS
LPARAM // handle to button (HWND)
);
Parameters
wParam
The low-order word contains the button's control identifier.
The high-order word specifies the notification message.
lParam
Handle to the button.
WM_CTLCOLORBTN
The WM_CTLCOLORBTN message is sent to the parent window of a button before drawing the button. The parent window can change the button's text and background colors. However, only owner-drawn buttons respond to the parent window processing this message.
LRESULT CALLBACK WindowProc(
HWND hwnd, // handle to window
UINT uMsg, // WM_CTLCOLORBTN
WPARAM // handle to button display context (HDC)
LPARAM // handle to button (HWND)
);
Parameters
wParam
Handle to the display context for the button.
lParam
Handle to the button.
Return Values
If an application processes this message, it must return a handle to a brush. The system uses the brush to paint the background of the button.
Remarks
By default, the DefWindowProc function selects the default system colors for the button. Buttons with the BS_PUSHBUTTON, BS_DEFPUSHBUTTON, or BS_PUSHLIKE styles do not use the returned brush. Buttons with these styles are always drawn with the default system colors. Drawing push buttons requires several different brushes-face, highlight and shadow-but the WM_CTLCOLORBTN message allows only one brush to be returned. To provide a custom appearance for push buttons, use an owner-drawn button.
The system does not automatically destroy the returned brush. It is the application's responsibility to destroy the brush when it is no longer needed.
The WM_CTLCOLORBTN message is never sent between threads. It is sent only within one thread.
The text color of a check box or radio button applies to the box or button, its check mark, and the text. The focus rectangle for these buttons remains the system default color (typically black). The text color of a group box applies to the text but not to the line that defines the box. The text color of a push button applies only to its focus rectangle; it does not affect the color of the text.
If a dialog box procedure handles this message, it should cast the desired return value to a BOOL and return the value directly. If the dialog box procedure returns FALSE, then default message handling is performed. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.