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