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.