Button (Windows Controls)

This section contains information about the programming elements used with button controls. A button is a control the user can click to provide input to an application.

Overviews

Topic	Contents
Button Messages	This topic discusses messages that are used with buttons.
Button States	This section discusses how selecting a button changes its state and how the application should respond.
Button Types	This topic discusses the different kinds of buttons.
Using Buttons	This section explains how to perform certains tasks associated with buttons.

Functions

Topic	Contents
CheckDlgButton	Changes the check state of a button control.
CheckRadioButton	Adds a check mark to (checks) a specified radio button in a group and removes a check mark from (clears) all other radio buttons in the group.
IsDlgButtonChecked	The IsDlgButtonChecked function determines whether a button control is checked or whether a three-state button control is checked, unchecked, or indeterminate.

Macros

Topic	Contents
Button_Enable	Enables or disables a button.
Button_GetCheck	Gets the check state of a radio button or check box. You can use this macro or send the BM_GETCHECK message explicitly.
Button_GetIdealSize	Gets the size of the button that best fits the text and image, if an image list is present. You can use this macro or send the BCM_GETIDEALSIZE message explicitly.
Button_GetImageList	Gets the BUTTON_IMAGELIST structure that describes the image list that is set for a button control. You can use this macro or send the BCM_GETIMAGELIST message explicitly.
Button_GetNote	Gets the text of the note associated with a command link button. You can use this macro or send the BCM_GETNOTE message explicitly.
Button_GetNoteLength	Gets the length of the note text that may be displayed in the description for a command link. Use this macro or send the BCM_GETNOTELENGTH message explicitly.
Button_GetSplitInfo	Gets information for a specified split button control. Use this macro or send the BCM_GETSPLITINFO message explicitly.
Button_GetState	Gets the check state of a radio button or check box. You can use this macro or send the BM_GETSTATE message explicitly.
Button_GetText	Gets the text of a button.
Button_GetTextLength	Gets the number of characters in the text of a button.
Button_GetTextMargin	Gets the margins used to draw text in a button control. You can use this macro or send the BCM_GETTEXTMARGIN message explicitly.
Button_SetCheck	Sets the check state of a radio button or check box. You can use this macro or send the BM_SETCHECK message explicitly.
Button_SetDropDownState	Sets the drop down state for a specified button with style of BS_SPLITBUTTON. Use this macro or send the BCM_SETDROPDOWNSTATE message explicitly.
Button_SetElevationRequiredState	Sets the elevation required state for a specified button or command link to display an elevated icon. Use this macro or send the BCM_SETSHIELD message explicitly.
Button_SetImageList	Assigns an image list to a button control. You can use this macro or send the BCM_SETIMAGELIST message explicitly.
Button_SetNote	Sets the text of the note associated with a specified command link button. You can use this macro or send the BCM_SETNOTE message explicitly.
Button_SetSplitInfo	Sets information for a specified split button control. Use this macro or send the BCM_SETSPLITINFO message explicitly.
Button_SetState	Sets the highlight state of a button. The highlight state indicates whether the button is highlighted as if the user had pushed it. You can use this macro or send the BM_SETSTATE message explicitly.
Button_SetStyle	Sets the style of a button. You can use this macro or send the BM_SETSTYLE message explicitly.
Button_SetText	Sets the text of a button.
Button_SetTextMargin	Sets the margins for drawing text in a button control. You can use this macro or send the BCM_SETTEXTMARGIN message explicitly.

Messages

Topic	Contents
BCM_GETIDEALSIZE	Gets the size of the button that best fits its text and image, if an image list is present. You can send this message explicitly or use the Button_GetIdealSize macro.
BCM_GETIMAGELIST	Gets the BUTTON_IMAGELIST structure that describes the image list assigned to a button control. You can send this message explicitly or use the Button_GetImageList macro.
BCM_GETNOTE	Gets the text of the note associated with a command link button. You can send this message explicitly or use the Button_GetNote macro.
BCM_GETNOTELENGTH	Gets the length of the note text that may be displayed in the description for a command link button. Send this message explicitly or by using the Button_GetNoteLength macro.
BCM_GETSPLITINFO	Gets information for a split button control. Send this message explicitly or by using the Button_GetSplitInfo macro.
BCM_GETTEXTMARGIN	Gets the margins used to draw text in a button control. You can send this message explicitly or use the Button_GetTextMargin macro.
BCM_SETDROPDOWNSTATE	Sets the drop down state for a button with style TBSTYLE_DROPDOWN. Send this message explicitly or by using the Button_SetDropDownState macro.
BCM_SETIMAGELIST	Assigns an image list to a button control. You can send this message explicitly or use the Button_SetImageList macro.
BCM_SETNOTE	Sets the text of the note associated with a command link button. You can send this message explicitly or use the Button_SetNote macro.
BCM_SETSHIELD	Sets the elevation required state for a specified button or command link to display an elevated icon. Send this message explicitly or by using the Button_SetElevationRequiredState macro.
BCM_SETSPLITINFO	Sets information for a split button control. Send this message explicitly or by using the Button_SetSplitInfo macro.
BCM_SETTEXTMARGIN	The BCM_SETTEXTMARGIN message sets the margins for drawing text in a button control.
BM_CLICK	Simulates 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 code.
BM_GETCHECK	Gets the check state of a radio button or check box. You can send this message explicitly or use the Button_GetCheck macro.
BM_GETIMAGE	Retrieves a handle to the image (icon or bitmap) associated with the button.
BM_GETSTATE	Retrieves the state of a button or check box. You can send this message explicitly or use the Button_GetState macro.
BM_SETCHECK	Sets the check state of a radio button or check box. You can send this message explicitly or by using the Button_SetCheck macro.
BM_SETDONTCLICK	Sets a flag on a radio button that controls the generation of BN_CLICKED messages when the button receives focus.
BM_SETIMAGE	Associates a new image (icon or bitmap) with the button.
BM_SETSTATE	Sets the highlight state of a button. The highlight state indicates whether the button is highlighted as if the user had pushed it. You can send this message explicitly or use the Button_SetState macro.
BM_SETSTYLE	Sets the style of a button. You can send this message explicitly or use the Button_SetStyle macro.

Notifications

Topic	Contents
BCN_DROPDOWN	Sent when the user clicks a drop down arrow on a button. The parent window of the control receives this notification code in the form of a WM_NOTIFY message.
BCN_HOTITEMCHANGE	Notifies the button control owner that the mouse is entering or leaving the client area of the button control. The button control sends this notification code in the form of a WM_NOTIFY message.
BN_CLICKED	Sent when the user clicks a button. The parent window of the button receives the BN_CLICKED notification code through the WM_COMMAND message.
BN_DBLCLK	Sent when the user double-clicks a button. This notification code 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.
BN_DISABLE	Sent when a button is disabled. Note: This notification code is provided only for compatibility with 16-bit versions of Windows earlier than version 3.0. Applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task. The parent window of the button receives the BN_DISABLE notification code through the WM_COMMAND message.
BN_DOUBLECLICKED	Sent when the user double-clicks a button. This notification code 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.
BN_HILITE	Sent when the user selects a button. Note: This notification code is provided only for compatibility with 16-bit versions of Windows earlier than version 3.0. Applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task. The parent window of the button receives the BN_HILITE notification code through the WM_COMMAND message.
BN_KILLFOCUS	Sent when a button loses the keyboard focus. The button must have the BS_NOTIFY style to send this notification code. The parent window of the button receives the BN_KILLFOCUS notification code through the WM_COMMAND message.
BN_PAINT	Sent when a button should be painted. Note: This notification code is provided only for compatibility with 16-bit versions of Windows earlier than version 3.0. Applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task. The parent window of the button receives the BN_PAINT notification code through the WM_COMMAND message.
BN_PUSHED	Sent when the push state of a button is set to pushed. Note: This notification code is provided only for compatibility with 16-bit versions of Windows earlier than version 3.0. Applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task. The parent window of the button receives the BN_PUSHED notification code through the WM_COMMAND message.
BN_SETFOCUS	Sent when a button receives the keyboard focus. The button must have the BS_NOTIFY style to send this notification code. The parent window of the button receives the BN_SETFOCUS notification code through the WM_COMMAND message.
BN_UNHILITE	Sent when the highlight should be removed from a button. Note: This notification code is provided only for compatibility with 16-bit versions of Windows earlier than version 3.0. Applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task. The parent window of the button receives the BN_UNHILITE notification code through the WM_COMMAND message.
BN_UNPUSHED	Sent when the push state of a button is set to unpushed. Note: This notification code is provided only for compatibility with 16-bit versions of Windows earlier than version 3.0. Applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task. The parent window of the button receives the BN_UNPUSHED notification code through the WM_COMMAND message.
NM_CUSTOMDRAW (button)	Notifies the parent window of a button control about custom draw operations on the button. The button control sends this notification code in the form of a WM_NOTIFY message.
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.

Structures

Topic	Contents
BUTTON_IMAGELIST	Contains information about an image list that is used with a button control.
BUTTON_SPLITINFO	Contains information that defines a split button (BS_SPLITBUTTON and BS_DEFSPLITBUTTON styles). Used with the BCM_GETSPLITINFO and BCM_SETSPLITINFO messages.
NMBCDROPDOWN	Contains information about a BCN_DROPDOWN notification.
NMBCHOTITEM	Contains information about the movement of the mouse over a button control.

Constants

Topic	Contents
Button Styles	Specifies a combination of button styles. If you create a button using the BUTTON class with the CreateWindow or CreateWindowEx function, you can specify any of the button styles listed below.