CButton Class

Article
04/28/2015

Provides the functionality of Windows button controls.

class CButton : public CWnd

Members

Public Constructors

Name	Description
CButton::CButton	Constructs a CButton object.

Public Methods

Name	Description
CButton::Create	Creates the Windows button control and attaches it to the CButton object.
CButton::DrawItem	Override to draw an owner-drawn CButton object.
CButton::GetBitmap	Retrieves the handle of the bitmap previously set with SetBitmap.
CButton::GetButtonStyle	Retrieves information about the button control style.
CButton::GetCheck	Retrieves the check state of a button control.
CButton::GetCursor	Retrieves the handle of the cursor image previously set with SetCursor.
CButton::GetIcon	Retrieves the handle of the icon previously set with SetIcon.
CButton::GetIdealSize	Retrieves the ideal size of the button control.
CButton::GetImageList	Retrieves the image list of the button control.
CButton::GetNote	Retrieves the note component of the current command link control.
CButton::GetNoteLength	Retrieves the length of the note text for the current command link control.
CButton::GetSplitGlyph	Retrieves the glyph associated with the current split button control.
CButton::GetSplitImageList	Retrieves the image list for the current split button control.
CButton::GetSplitInfo	Retrieves information that defines the current split button control.
CButton::GetSplitSize	Retrieves the bounding rectangle of the drop-down component of the current split button control.
CButton::GetSplitStyle	Retrieves the split button styles that define the current split button control.
CButton::GetState	Retrieves the check state, highlight state, and focus state of a button control.
CButton::GetTextMargin	Retrieves the text margin of the button control.
CButton::SetBitmap	Specifies a bitmap to be displayed on the button.
CButton::SetButtonStyle	Changes the style of a button.
CButton::SetCheck	Sets the check state of a button control.
CButton::SetCursor	Specifies a cursor image to be displayed on the button.
CButton::SetDropDownState	Sets the drop-down state of the current split button control.
CButton::SetIcon	Specifies an icon to be displayed on the button.
CButton::SetImageList	Sets the image list of the button control.
CButton::SetNote	Sets the note on the current command link control.
CButton::SetSplitGlyph	Associates a specified glyph with the current split button control.
CButton::SetSplitImageList	Associates an image list with the current split button control.
CButton::SetSplitInfo	Specifies information that defines the current split button control.
CButton::SetSplitSize	Sets the bounding rectangle of the drop-down component of the current split button control.
CButton::SetSplitStyle	Sets the style of the current split button control.
CButton::SetState	Sets the highlighting state of a button control.
CButton::SetTextMargin	Sets the text margin of the button control.

Remarks

A button control is a small, rectangular child window that can be clicked on and off. Buttons can be used alone or in groups and can either be labeled or appear without text. A button typically changes appearance when the user clicks it.

Typical buttons are the check box, radio button, and pushbutton. A CButton object can become any of these, according to the button style specified at its initialization by the Create member function.

In addition, the CBitmapButton class derived from CButton supports creation of button controls labeled with bitmap images instead of text. A CBitmapButton can have separate bitmaps for a button's up, down, focused, and disabled states.

You can create a button control either from a dialog template or directly in your code. In both cases, first call the constructor CButton to construct the CButton object; then call the Create member function to create the Windows button control and attach it to the CButton object.

Construction can be a one-step process in a class derived from CButton. Write a constructor for the derived class and call Create from within the constructor.

If you want to handle Windows notification messages sent by a button control to its parent (usually a class derived from CDialog), add a message-map entry and message-handler member function to the parent class for each message.

Each message-map entry takes the following form:

ON_Notification( id, memberFxn )

where id specifies the child window ID of the control sending the notification and memberFxn is the name of the parent member function you have written to handle the notification.

The parent's function prototype is as follows:

afx_msg void memberFxn**( );**

Potential message-map entries are as follows:

Map entry	Sent to parent when...
ON_BN_CLICKED	The user clicks a button.
ON_BN_DOUBLECLICKED	The user double-clicks a button.

If you create a CButton object from a dialog resource, the CButton object is automatically destroyed when the user closes the dialog box.

If you create a CButton object within a window, you may need to destroy it. If you create the CButton object on the heap by using the new function, you must call delete on the object to destroy it when the user closes the Windows button control. If you create the CButton object on the stack, or it is embedded in the parent dialog object, it is destroyed automatically.