Edit

CButton Class

  • Article

Provides the functionality of Windows button controls.

Syntax

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.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CButton

Requirements

Header: afxwin.h

CButton::CButton

Constructs a CButton object.

CButton();

Example

// Declare a button object.
CButton myButton;

CButton::Create

Creates the Windows button control and attaches it to the CButton object.

virtual BOOL Create(
    LPCTSTR lpszCaption,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parameters

lpszCaption
Specifies the button control's text.

dwStyle
Specifies the button control's style. Apply any combination of button styles to the button.

rect
Specifies the button control's size and position. It can be either a CRect object or a RECT structure.

pParentWnd
Specifies the button control's parent window, usually a CDialog. It must not be NULL.

nID
Specifies the button control's ID.

Return Value

Nonzero if successful; otherwise 0.

Remarks

You construct a CButton object in two steps. First, call the constructor and then call Create, which creates the Windows button control and attaches it to the CButton object.

If the WS_VISIBLE style is given, Windows sends the button control all the messages required to activate and show the button.

Apply the following window styles to a button control:

  • WS_CHILD Always

  • WS_VISIBLE Usually

  • WS_DISABLED Rarely

  • WS_GROUP To group controls

  • WS_TABSTOP To include the button in the tabbing order

Example

CButton myButton1, myButton2, myButton3, myButton4;

// Create a push button.
myButton1.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON,
                 CRect(10, 10, 100, 30), pParentWnd, 1);

// Create a radio button.
myButton2.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_RADIOBUTTON,
                 CRect(10, 40, 100, 70), pParentWnd, 2);

// Create an auto 3-state button.
myButton3.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_AUTO3STATE,
                 CRect(10, 70, 100, 100), pParentWnd, 3);

// Create an auto check box.
myButton4.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_AUTOCHECKBOX,
                 CRect(10, 100, 100, 130), pParentWnd, 4);

CButton::DrawItem

Called by the framework when a visual aspect of an owner-drawn button has changed.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parameters

lpDrawItemStruct
A long pointer to a DRAWITEMSTRUCT structure. The structure contains information about the item to be drawn and the type of drawing required.

Remarks

An owner-drawn button has the BS_OWNERDRAW style set. Override this member function to implement drawing for an owner-drawn CButton object. The application should restore all graphics device interface (GDI) objects selected for the display context supplied in lpDrawItemStruct before the member function terminates.

Also see the BS_ style values.

Example

// NOTE: CMyButton is a class derived from CButton. The CMyButton
// object was created as follows:
//
// CMyButton myButton;
// myButton.Create(_T("My button"),
//      WS_CHILD|WS_VISIBLE|BS_PUSHBUTTON|BS_OWNERDRAW,
//      CRect(10,10,100,30), pParentWnd, 1);
//

// This example implements the DrawItem method for a CButton-derived
// class that draws the button's text using the color red.
void CMyButton::DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct)
{
   UINT uStyle = DFCS_BUTTONPUSH;

   // This code only works with buttons.
   ASSERT(lpDrawItemStruct->CtlType == ODT_BUTTON);

   // If drawing selected, add the pushed style to DrawFrameControl.
   if (lpDrawItemStruct->itemState & ODS_SELECTED)
      uStyle |= DFCS_PUSHED;

   // Draw the button frame.
   ::DrawFrameControl(lpDrawItemStruct->hDC, &lpDrawItemStruct->rcItem,
                      DFC_BUTTON, uStyle);

   // Get the button's text.
   CString strText;
   GetWindowText(strText);

   // Draw the button text using the text color red.
   COLORREF crOldColor = ::SetTextColor(lpDrawItemStruct->hDC, RGB(255, 0, 0));
   ::DrawText(lpDrawItemStruct->hDC, strText, strText.GetLength(),
              &lpDrawItemStruct->rcItem, DT_SINGLELINE | DT_VCENTER | DT_CENTER);
   ::SetTextColor(lpDrawItemStruct->hDC, crOldColor);
}

CButton::GetBitmap

Call this member function to get the handle of a bitmap, previously set with SetBitmap, that is associated with a button.

HBITMAP GetBitmap() const;

Return Value

A handle to a bitmap. NULL if no bitmap is previously specified.

Example

CButton myBitmapButton;

// Create a bitmap button.
myBitmapButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_BITMAP,
                      CRect(10, 10, 60, 50), pParentWnd, 1);

// If no bitmap is defined for the button, define the bitmap to the
// system close bitmap.
if (myBitmapButton.GetBitmap() == NULL)
   myBitmapButton.SetBitmap(::LoadBitmap(NULL, MAKEINTRESOURCE(OBM_CLOSE)));

CButton::GetButtonStyle

Retrieves information about the button control style.

UINT GetButtonStyle() const;

Return Value

Returns the button styles for this CButton object. This function returns only the BS_ style values, not any of the other window styles.

Example

CButton myRadioButton;

// Create a radio button.
myRadioButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_RADIOBUTTON,
                     CRect(10, 10, 100, 30), pParentWnd, 1);

// Change the button style to use one of the "auto" styles; for
// push button, change to def push button.
UINT uStyle = myRadioButton.GetButtonStyle();
if (uStyle == BS_PUSHBUTTON)
   uStyle = BS_DEFPUSHBUTTON;
else if (uStyle == BS_RADIOBUTTON)
   uStyle = BS_AUTORADIOBUTTON;
else if (uStyle == BS_CHECKBOX)
   uStyle = BS_AUTOCHECKBOX;
else if (uStyle == BS_3STATE)
   uStyle = BS_AUTO3STATE;

// Change the button style to the one wanted.
myRadioButton.SetButtonStyle(uStyle);

CButton::GetCheck

Retrieves the check state of a radio button or check box.

int GetCheck() const;

Return Value

The return value from a button control created with the BS_AUTOCHECKBOX, BS_AUTORADIOBUTTON, BS_AUTO3STATE, BS_CHECKBOX, BS_RADIOBUTTON, or BS_3STATE style is one of the following values:

Value Meaning
BST_UNCHECKED Button state is unchecked.
BST_CHECKED Button state is checked.
BST_INDETERMINATE Button state is indeterminate (applies only if the button has the BS_3STATE or BS_AUTO3STATE style).

If the button has any other style, the return value is BST_UNCHECKED.

Example

CButton myA3Button;

// Create an auto 3-state button.
myA3Button.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_AUTO3STATE,
                  CRect(10, 10, 100, 30), pParentWnd, 1);

// Set the check state to the next state
// (i.e. BST_UNCHECKED changes to BST_CHECKED
// BST_CHECKED changes to BST_INDETERMINATE
// BST_INDETERMINATE changes to BST_UNCHECKED).
myA3Button.SetCheck(((myA3Button.GetCheck() + 1) % 3));

CButton::GetCursor

Call this member function to get the handle of a cursor, previously set with SetCursor, that is associated with a button.

HCURSOR GetCursor();

Return Value

A handle to a cursor image. NULL if no cursor is previously specified.

Example

CButton myIconButton;

// Create an icon button.
myIconButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_ICON,
                    CRect(10, 10, 60, 50), pParentWnd, 1);

// If no image is defined for the button, define the image to the
// system arrow and question mark cursor.
if (myIconButton.GetCursor() == NULL)
   myIconButton.SetCursor(::LoadCursor(NULL, IDC_HELP));

CButton::GetIcon

Call this member function to get the handle of an icon, previously set with SetIcon, that is associated with a button.

HICON GetIcon() const;

Return Value

A handle to an icon. NULL if no icon is previously specified.

Example

CButton myIconButton2;

// Create an icon button.
myIconButton2.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_ICON,
                     CRect(10, 10, 60, 50), pParentWnd, 1);

// If no icon is defined for the button, define the icon to the
// system error icon.
if (myIconButton2.GetIcon() == NULL)
   myIconButton2.SetIcon(::LoadIcon(NULL, IDI_ERROR));

CButton::GetIdealSize

Retrieves the ideal size for the button control.

BOOL GetIdealSize(SIZE* psize);

Parameters

psize
A pointer to the current size of the button.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function emulates the functionality of the BCM_GETIDEALSIZE message, as described in the Buttons section of the Windows SDK.

CButton::GetImageList

Call this method to get the image list from the button control.

BOOL GetImageList(PBUTTON_IMAGELIST pbuttonImagelist);

Parameters

pbuttonImagelist
A pointer to the image list of the CButton object.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function emulates the functionality of the BCM_GETIMAGELIST message, as described in the Buttons section of the Windows SDK.

CButton::GetNote

Retrieves the note text associated with the current command link control.

CString GetNote() const;

BOOL GetNote(
    LPTSTR lpszNote,
    UINT* cchNote) const;

Parameters

lpszNote
[out] Pointer to a buffer, which the caller is responsible for allocating and deallocating. If the return value is TRUE, the buffer contains the note text that is associated with the current command link control; otherwise, the buffer is unchanged.

cchNote
[in, out] A pointer to an unsigned integer variable. When this method is called, the variable contains the size of the buffer specified by the lpszNote parameter. When this method returns, if the return value is TRUE the variable contains the size of the note associated with the current command link control. If the return value is FALSE, the variable contains the buffer size required to contain the note.

Return Value

In the first overload, a CString object that contains the note text associated with the current command link control.

-or-

In the second overload, TRUE if this method is successful; otherwise, FALSE.

Remarks

Use this method only with controls whose button style is BS_COMMANDLINK or BS_DEFCOMMANDLINK.

This method sends the BCM_GETNOTE message, which is described in the Windows SDK.

CButton::GetNoteLength

Retrieves the length of the note text for the current command link control.

UINT GetNoteLength() const;

Return Value

The length of the note text, in 16-bit Unicode characters, for the current command link control.

Remarks

Use this method only with controls whose button style is BS_COMMANDLINK or BS_DEFCOMMANDLINK.

This method sends the BCM_GETNOTELENGTH message, which is described in the Windows SDK.

CButton::GetSplitGlyph

Retrieves the glyph associated with the current split button control.

TCHAR GetSplitGlyph() const;

Return Value

The glyph character associated with the current split button control.

Remarks

A glyph is the physical representation of a character in a particular font. For example, a split button control might be decorated with the glyph of the Unicode check mark character (U+2713).

Use this method only with controls whose button style is BS_SPLITBUTTON or BS_DEFSPLITBUTTON.

This method initializes the mask member of a BUTTON_SPLITINFO structure with the BCSIF_GLYPH flag, and then sends that structure in the BCM_GETSPLITINFO message that is described in the Windows SDK. When the message function returns, this method retrieves the glyph from the himlGlyph member of the structure.

CButton::GetSplitImageList

Retrieves the image list for the current split button control.

CImageList* GetSplitImageList() const;

Return Value

A pointer to a CImageList object.

Remarks

Use this method only with controls whose button style is BS_SPLITBUTTON or BS_DEFSPLITBUTTON.

This method initializes the mask member of a BUTTON_SPLITINFO structure with the BCSIF_IMAGE flag, and then sends that structure in the BCM_GETSPLITINFO message that is described in the Windows SDK. When the message function returns, this method retrieves the image list from the himlGlyph member of the structure.

CButton::GetSplitInfo

Retrieves parameters that determine how Windows draws the current split button control.

BOOL GetSplitInfo(PBUTTON_SPLITINFO pInfo) const;

Parameters

pInfo
[out] Pointer to a BUTTON_SPLITINFO structure that receives information about the current split button control. The caller is responsible for allocating the structure.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

Use this method only with controls whose button style is BS_SPLITBUTTON or BS_DEFSPLITBUTTON.

This method sends the BCM_GETSPLITINFO message, which is described in the Windows SDK.

CButton::GetSplitSize

Retrieves the bounding rectangle of the drop-down component of the current split button control.

BOOL GetSplitSize(LPSIZE pSize) const;

Parameters

pSize
[out] Pointer to a SIZE structure that receives the description of a rectangle.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

Use this method only with controls whose button style is BS_SPLITBUTTON or BS_DEFSPLITBUTTON.

When the split button control is expanded, it can display a drop-down component such as a list control or pager control. This method retrieves the bounding rectangle that contains the drop-down component.

This method initializes the mask member of a BUTTON_SPLITINFO structure with the BCSIF_SIZE flag, and then sends that structure in the BCM_GETSPLITINFO message that is described in the Windows SDK. When the message function returns, this method retrieves the bounding rectangle from the size member of the structure.

CButton::GetSplitStyle

Retrieves the split button styles that define the current split button control.

UINT GetSplitStyle() const;

Return Value

A bitwise combination of split button styles. For more information, see the uSplitStyle member of the BUTTON_SPLITINFO structure.

Remarks

Use this method only with controls whose button style is BS_SPLITBUTTON or BS_DEFSPLITBUTTON.

The split button styles specify the alignment, aspect ratio, and graphical format with which Windows draws a split button icon.

This method initializes the mask member of a BUTTON_SPLITINFO structure with the BCSIF_STYLE flag, and then sends that structure in the BCM_GETSPLITINFO message that is described in the Windows SDK. When the message function returns, this method retrieves the split button styles from the uSplitStyle member of the structure.

CButton::GetState

Retrieves the state of a button control.

UINT GetState() const;

Return Value

A bit field that contains the combination of values that indicate the current state of a button control. The following table lists possible values.

Button State Value Description
BST_UNCHECKED 0x0000 The initial state.
BST_CHECKED 0x0001 The button control is checked.
BST_INDETERMINATE 0x0002 The state is indeterminate (only possible when the button control has three states).
BST_PUSHED 0x0004 The button control is pressed.
BST_FOCUS 0x0008 The button control has the focus.

Remarks

A button control with the BS_3STATE or BS_AUTO3STATE button style creates a check box that has a third state that is named the indeterminate state. The indeterminate state indicates that the check box is neither checked nor unchecked.

Example

CButton myPushButton;

// Create a push button.
myPushButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON,
                    CRect(10, 10, 100, 30), pParentWnd, 1);

// Invert the highlight state of the button.
myPushButton.SetState(!(myPushButton.GetState() & 0x0004));

CButton::GetTextMargin

Call this method to get the text margin of the CButton object.

BOOL GetTextMargin(RECT* pmargin);

Parameters

pmargin
A pointer to the text margin of the CButton object.

Return Value

Returns the text margin. Nonzero if successful; otherwise 0.

Remarks

This member function emulates the functionality of the BCM_GETTEXTMARGIN message, as described in the Buttons section of the Windows SDK.

CButton::SetBitmap

Call this member function to associate a new bitmap with the button.

HBITMAP SetBitmap(HBITMAP hBitmap);

Parameters

hBitmap
The handle of a bitmap.

Return Value

The handle of a bitmap previously associated with the button.

Remarks

The bitmap will be automatically placed on the face of the button, centered by default. If the bitmap is too large for the button, it will be clipped on either side. You can choose other alignment options, including the following:

  • BS_TOP

  • BS_LEFT

  • BS_RIGHT

  • BS_CENTER

  • BS_BOTTOM

  • BS_VCENTER

Unlike CBitmapButton, which uses four bitmaps per button, SetBitmap uses only one bitmap per the button. When the button is pressed, the bitmap appears to shift down and to the right.

You are responsible for releasing the bitmap when you are done with it.

Example

CButton myBitmapButton;

// Create a bitmap button.
myBitmapButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_BITMAP,
                      CRect(10, 10, 60, 50), pParentWnd, 1);

// If no bitmap is defined for the button, define the bitmap to the
// system close bitmap.
if (myBitmapButton.GetBitmap() == NULL)
   myBitmapButton.SetBitmap(::LoadBitmap(NULL, MAKEINTRESOURCE(OBM_CLOSE)));

CButton::SetButtonStyle

Changes the style of a button.

void SetButtonStyle(
    UINT nStyle,
    BOOL bRedraw = TRUE);

Parameters

nStyle
Specifies the button style.

bRedraw
Specifies whether the button is to be redrawn. A nonzero value redraws the button. A 0 value does not redraw the button. The button is redrawn by default.

Remarks

Use the GetButtonStyle member function to retrieve the button style. The low-order word of the complete button style is the button-specific style.

Example

CButton myRadioButton;

// Create a radio button.
myRadioButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_RADIOBUTTON,
                     CRect(10, 10, 100, 30), pParentWnd, 1);

// Change the button style to use one of the "auto" styles; for
// push button, change to def push button.
UINT uStyle = myRadioButton.GetButtonStyle();
if (uStyle == BS_PUSHBUTTON)
   uStyle = BS_DEFPUSHBUTTON;
else if (uStyle == BS_RADIOBUTTON)
   uStyle = BS_AUTORADIOBUTTON;
else if (uStyle == BS_CHECKBOX)
   uStyle = BS_AUTOCHECKBOX;
else if (uStyle == BS_3STATE)
   uStyle = BS_AUTO3STATE;

// Change the button style to the one wanted.
myRadioButton.SetButtonStyle(uStyle);

CButton::SetCheck

Sets or resets the check state of a radio button or check box.

void SetCheck(int nCheck);

Parameters

nCheck
Specifies the check state. This parameter can be one of the following:

Value Meaning
BST_UNCHECKED Set the button state to unchecked.
BST_CHECKED Set the button state to checked.
BST_INDETERMINATE Set the button state to indeterminate. This value can be used only if the button has the BS_3STATE or BS_AUTO3STATE style.

Remarks

This member function has no effect on a pushbutton.

Example

CButton myA3Button;

// Create an auto 3-state button.
myA3Button.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_AUTO3STATE,
                  CRect(10, 10, 100, 30), pParentWnd, 1);

// Set the check state to the next state
// (i.e. BST_UNCHECKED changes to BST_CHECKED
// BST_CHECKED changes to BST_INDETERMINATE
// BST_INDETERMINATE changes to BST_UNCHECKED).
myA3Button.SetCheck(((myA3Button.GetCheck() + 1) % 3));

CButton::SetCursor

Call this member function to associate a new cursor with the button.

HCURSOR SetCursor(HCURSOR hCursor);

Parameters

hCursor
The handle of a cursor.

Return Value

The handle of a cursor previously associated with the button.

Remarks

The cursor will be automatically placed on the face of the button, centered by default. If the cursor is too large for the button, it will be clipped on either side. You can choose other alignment options, including the following:

  • BS_TOP

  • BS_LEFT

  • BS_RIGHT

  • BS_CENTER

  • BS_BOTTOM

  • BS_VCENTER

Unlike CBitmapButton, which uses four bitmaps per button, SetCursor uses only one cursor per the button. When the button is pressed, the cursor appears to shift down and to the right.

Example

CButton myIconButton;

// Create an icon button.
myIconButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_ICON,
                    CRect(10, 10, 60, 50), pParentWnd, 1);

// If no image is defined for the button, define the image to the
// system arrow and question mark cursor.
if (myIconButton.GetCursor() == NULL)
   myIconButton.SetCursor(::LoadCursor(NULL, IDC_HELP));

CButton::SetDropDownState

Sets the drop-down state of the current split button control.

BOOL SetDropDownState(BOOL fDropDown);

Parameters

fDropDown
[in] TRUE to set BST_DROPDOWNPUSHED state; otherwise, FALSE.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

A split button control has a style of BS_SPLITBUTTON or BS_DEFSPLITBUTTON and consists of a button and a drop-down arrow to its right. For more information, see Button Styles. Usually, the drop-down state is set when the user clicks the drop-down arrow. Use this method to programmatically set the drop-down state of the control. The drop-down arrow is drawn shaded to indicate the state.

This method sends the BCM_SETDROPDOWNSTATE message, which is described in the Windows SDK.

Example

The first code example defines the variable, m_splitButton, that is used to programmatically access the split button control. This variable is used in the following example.

public:
// Variable to access programatically defined command link control.
CButton m_cmdLink;
// Variable to access programatically defined split button control.
CButton m_splitButton;

The next code example sets the state of the split button control to indicate that the drop-down arrow is pushed.

/* Set the state of the split button control to indicate that 
   the drop-down arrow is pushed. The arrow is drawn shaded to 
   indicate the state.
   */
m_splitButton.SetDropDownState(TRUE);

CButton::SetElevationRequired

Sets the state of the current button control to elevation required, which is necessary for the control to display an elevated security icon.

BOOL SetElevationRequired(BOOL fElevationRequired);

Parameters

fElevationRequired
[in] TRUE to set elevation required state; otherwise, FALSE.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

If a button or command link control requires elevated security permission to perform an action, set the control to elevation required state. Subsequently, Windows displays the User Account Control (UAC) shield icon on the control. For more information, see User Account Control.

This method sends the BCM_SETSHIELD message, which is described in the Windows SDK.

CButton::SetIcon

Call this member function to associate a new icon with the button.

HICON SetIcon(HICON hIcon);

Parameters

hIcon
The handle of an icon.

Return Value

The handle of an icon previously associated with the button.

Remarks

The icon will be automatically placed on the face of the button, centered by default. If the icon is too large for the button, it will be clipped on either side. You can choose other alignment options, including the following:

  • BS_TOP

  • BS_LEFT

  • BS_RIGHT

  • BS_CENTER

  • BS_BOTTOM

  • BS_VCENTER

Unlike CBitmapButton, which uses four bitmaps per button, SetIcon uses only one icon per the button. When the button is pressed, the icon appears to shift down and to the right.

Example

CButton myIconButton2;

// Create an icon button.
myIconButton2.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_ICON,
                     CRect(10, 10, 60, 50), pParentWnd, 1);

// If no icon is defined for the button, define the icon to the
// system error icon.
if (myIconButton2.GetIcon() == NULL)
   myIconButton2.SetIcon(::LoadIcon(NULL, IDI_ERROR));

CButton::SetImageList

Call this method to set the image list of the CButton object.

BOOL SetImageList(PBUTTON_IMAGELIST pbuttonImagelist);

Parameters

pbuttonImagelist
A pointer to the new image list.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This member function emulates the functionality of the BCM_SETIMAGELIST message, as described in the Buttons section of the Windows SDK.

CButton::SetNote

Sets the note text for the current command link control.

BOOL SetNote(LPCTSTR lpszNote);

Parameters

lpszNote
[in] Pointer to a Unicode string that is set as the note text for the command link control.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

Use this method only with controls whose button style is BS_COMMANDLINK or BS_DEFCOMMANDLINK.

This method sends the BCM_SETNOTE message, which is described in the Windows SDK.

Example

The first code example defines the variable, m_cmdLink, that is used to programmatically access the command link control. This variable is used in the following example.

public:
// Variable to access programatically defined command link control.
CButton m_cmdLink;
// Variable to access programatically defined split button control.
CButton m_splitButton;

The next code example sets the note text for the command link control.

// Set the command link text.
m_cmdLink.SetNote(_T("This is the command link note."));

CButton::SetSplitGlyph

Associates a specified glyph with the current split button control.

BOOL SetSplitGlyph(TCHAR chGlyph);

Parameters

chGlyph
[in] A character that specifies the glyph to use as the split button drop-down arrow.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

Use this method only with controls that have the button style BS_SPLITBUTTON or BS_DEFSPLITBUTTON.

A glyph is the physical representation of a character in a particular font. The chGlyph parameter is not used as the glyph, but is instead used to select a glyph from a set of system-defined glyphs. The default drop-down arrow glyph is specified by a character '6', and resembles the Unicode character BLACK DOWN-POINTING TRIANGLE (U+25BC).

This method initializes the mask member of a BUTTON_SPLITINFO structure with the BCSIF_GLYPH flag and the himlGlyph member with the chGlyph parameter, and then sends that structure in the BCM_GETSPLITINFO message that is described in the Windows SDK.

CButton::SetSplitImageList

Associates an image list with the current split button control.

BOOL SetSplitImageList(CImageList* pSplitImageList);

Parameters

pSplitImageList
[in] Pointer to a CImageList object to assign to the current split button control.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

Use this method only with controls whose button style is BS_SPLITBUTTON or BS_DEFSPLITBUTTON.

This method initializes the mask member of a BUTTON_SPLITINFO structure with the BCSIF_IMAGE flag and the himlGlyph member with the pSplitImageList parameter, and then sends that structure in the BCM_GETSPLITINFO message that is described in the Windows SDK.

CButton::SetSplitInfo

Specifies parameters that determine how Windows draws the current split button control.

BOOL SetSplitInfo(PBUTTON_SPLITINFO pInfo);

Parameters

pInfo
[in] Pointer to a BUTTON_SPLITINFO structure that defines the current split button control.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

Use this method only with controls whose button style is BS_SPLITBUTTON or BS_DEFSPLITBUTTON.

This method sends the BCM_SETSPLITINFO message, which is described in the Windows SDK.

Example

The first code example defines the variable, m_splitButton, that is used to programmatically access the split button control.

public:
// Variable to access programatically defined command link control.
CButton m_cmdLink;
// Variable to access programatically defined split button control.
CButton m_splitButton;

The next code example changes the glyph that is used for the split button drop-down arrow. The example substitutes an up-pointing triangle glyph for the default down-pointing triangle glyph. The glyph that is displayed depends on the character that you specify in the himlGlyph member of the BUTTON_SPLITINFO structure. The down-pointing triangle glyph is specified by a character '6' and the up-pointing triangle glyph is specified by a character '5'. For comparison, see the convenience method, CButton::SetSplitGlyph.

/* 
   The drop-down arrow glyph is a function of the specified character. 
   The default "down" drop-down arrow glyph is specified by a 
   character '6'. Set the "up" arrow glyph, which is a character '5'.
   See the convenience method, SetSplitGlyph(), for comparison.
   */
BUTTON_SPLITINFO bsInfo = {0};
bsInfo.mask = BCSIF_GLYPH;
TCHAR chGlyph = _T('5'); // "up" arrow glyph
bsInfo.himlGlyph = (HIMAGELIST)chGlyph;
bRC = m_splitButton.SetSplitInfo(&bsInfo);

CButton::SetSplitSize

Sets the bounding rectangle of the drop-down component of the current split button control.

BOOL SetSplitSize(LPSIZE pSize);

Parameters

pSize
[in] Pointer to a SIZE structure that describes a bounding rectangle.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

Use this method only with controls whose button style is BS_SPLITBUTTON or BS_DEFSPLITBUTTON.

When the split button control is expanded, it can display a drop-down component such as a list control or pager control. This method specifies the size of the bounding rectangle that contains the drop-down component.

This method initializes the mask member of a BUTTON_SPLITINFO structure with the BCSIF_SIZE flag and the size member with the pSize parameter, and then sends that structure in the BCM_GETSPLITINFO message that is described in the Windows SDK.

Example

The first code example defines the variable, m_splitButton, that is used to programmatically access the split button control. This variable is used in the following example.

public:
// Variable to access programatically defined command link control.
CButton m_cmdLink;
// Variable to access programatically defined split button control.
CButton m_splitButton;

The next code example doubles the size of the split button drop-down arrow.

// Double the size of the split button drop-down arrow.
SIZE sz;
bRC = m_splitButton.GetSplitSize(&sz); // current size
sz.cx = sz.cx * 2;
sz.cy = sz.cy * 2;
bRC = m_splitButton.SetSplitSize(&sz);

CButton::SetSplitStyle

Sets the style of the current split button control.

BOOL SetSplitStyle(UINT uSplitStyle);

Parameters

uSplitStyle
[in] A bitwise combination of split button styles. For more information, see the uSplitStyle member of the BUTTON_SPLITINFO structure.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

Use this method only with controls whose button style is BS_SPLITBUTTON or BS_DEFSPLITBUTTON.

The split button styles specify the alignment, aspect ratio, and graphical format with which Windows draws a split button icon. For more information, see the uSplitStyle member of the BUTTON_SPLITINFO structure.

This method initializes the mask member of a BUTTON_SPLITINFO structure with the BCSIF_STYLE flag and the uSplitStyle member with the uSplitStyle parameter, and then sends that structure in the BCM_GETSPLITINFO message that is described in the Windows SDK.

Example

The first code example defines the variable, m_splitButton, that is used to programmatically access the split button control.

public:
// Variable to access programatically defined command link control.
CButton m_cmdLink;
// Variable to access programatically defined split button control.
CButton m_splitButton;

The next code example sets the style of the split button drop-down arrow. The BCSS_ALIGNLEFT style displays the arrow on the left side of the button, and the BCSS_STRETCH style retains the drop-down arrow's proportions when you resize the button.

/* 
    Set the style of the split button drop-down arrow: Display the 
    arrow on the left and retain the arrow's proportions when resizing 
    the control.
    */
bRC = m_splitButton.SetSplitStyle(BCSS_ALIGNLEFT | BCSS_STRETCH);

CButton::SetState

Sets whether a button control is highlighted or not.

void SetState(BOOL bHighlight);

Parameters

bHighlight
Specifies whether the button is to be highlighted. A nonzero value highlights the button; a 0 value removes any highlighting.

Remarks

Highlighting affects the exterior of a button control. It has no effect on the check state of a radio button or check box.

A button control is automatically highlighted when the user clicks and holds the left mouse button. The highlighting is removed when the user releases the mouse button.

Example

CButton myPushButton;

// Create a push button.
myPushButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON,
                    CRect(10, 10, 100, 30), pParentWnd, 1);

// Invert the highlight state of the button.
myPushButton.SetState(!(myPushButton.GetState() & 0x0004));

CButton::SetTextMargin

Call this method to set the text margin of the CButton object.

BOOL SetTextMargin(RECT* pmargin);

Parameters

pmargin
A pointer to the new text margin.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This member function emulates the functionality of the BCM_SETTEXTMARGIN message, as described in the Buttons section of the Windows SDK.

See also

CWnd Class
Hierarchy Chart
CWnd Class
CComboBox Class
CEdit Class
CListBox Class
CScrollBar Class
CStatic Class
CBitmapButton Class
CDialog Class