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.