Button
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. |