CButton 类

项目
10/17/2023

提供 Windows 按钮控件功能。

语法

class CButton : public CWnd

成员

公共构造函数

名称	描述
CButton::CButton	构造 `CButton` 对象。

公共方法

名称	描述
CButton::Create	创建 Windows 按钮控件并将其附加到 `CButton` 对象。
CButton::DrawItem	重写以绘制所有者绘制的 `CButton` 对象。
CButton::GetBitmap	检索先前使用 SetBitmap 设置的位图的句柄。
CButton::GetButtonStyle	检索有关按钮控件样式的信息。
CButton::GetCheck	检索按钮控件的选中状态。
CButton::GetCursor	检索先前使用 SetCursor 设置的光标图像的句柄。
CButton::GetIcon	检索先前使用 SetIcon 设置的图标的句柄。
CButton::GetIdealSize	检索按钮控件的理想大小。
CButton::GetImageList	检索按钮控件的图像列表。
CButton::GetNote	检索当前命令链接控件的注释组件。
CButton::GetNoteLength	检索当前命令链接控件的注释文本的长度。
CButton::GetSplitGlyph	检索与当前拆分按钮控件关联的字形。
CButton::GetSplitImageList	检索当前拆分按钮控件的图像列表。
CButton::GetSplitInfo	检索用于定义当前拆分按钮控件的信息。
CButton::GetSplitSize	检索当前拆分按钮控件的下拉组件的边框。
CButton::GetSplitStyle	检索用于定义当前拆分按钮控件的拆分按钮样式。
CButton::GetState	检索按钮控件的选中状态、突出显示状态和焦点状态。
CButton::GetTextMargin	检索按钮控件的文本边距。
CButton::SetBitmap	指定要在按钮上显示的位图。
CButton::SetButtonStyle	更改按钮的样式。
CButton::SetCheck	设置按钮控件的选中状态。
CButton::SetCursor	指定要在按钮上显示的光标图像。
CButton::SetDropDownState	设置当前拆分按钮控件的下拉状态。
CButton::SetIcon	指定要在按钮上显示的图标。
CButton::SetImageList	设置按钮控件的图像列表。
CButton::SetNote	在当前命令链接控件上设置注释。
CButton::SetSplitGlyph	将指定的字形与当前拆分按钮控件相关联。
CButton::SetSplitImageList	将图像列表与当前拆分按钮控件相关联。
CButton::SetSplitInfo	指定用于定义当前拆分按钮控件的信息。
CButton::SetSplitSize	设置当前拆分按钮控件的下拉组件的边框。
CButton::SetSplitStyle	设置当前拆分按钮控件的样式。
CButton::SetState	设置按钮控件的突出显示状态。
CButton::SetTextMargin	设置按钮控件的文本边距。

注解

按钮控件是一个可以单击打开和关闭的较小矩形子窗口。按钮可以单独使用，也可以成组使用；可以带有标签，也可以不显示文本。当用户单击某个按钮时，该按钮的外观通常会改变。

典型的按钮包括复选框、单选按钮和按钮。根据 Create 成员函数在初始化 CButton 对象时指定的按钮样式，该对象可以变成上述任何一种按钮。

此外，从 CButton 派生的 CBitmapButton 类支持创建标有位图图像而不是文本的按钮控件。 CBitmapButton 可为按钮的未按下、按下、聚焦和禁用状态提供单独的位图。

可以从对话框模板创建按钮控件，也可以直接在代码中创建按钮控件。在这两种情况下，首先调用构造函数 CButton 以构造 CButton 对象，然后调用 Create 成员函数以创建 Windows 按钮控件，并将它附加到 CButton 对象。

构造可以是派生自 CButton 的类中的单步过程。为派生类编写构造函数并从构造函数中调用 Create。

如果你要处理由按钮控件发送到其父级（通常是从 CDialog 派生的类）的 Windows 通知消息，请将消息映射条目和消息处理程序成员函数添加到每个消息的父类。

每个消息映射条目采用以下格式：

ON_Notification （id， memberFxn）

其中 id 指定发送通知的组合框控件的子窗口 ID，memberFxn 是为处理通知而编写的父成员函数的名称。

父函数原型如下：

afx_msg void memberFxn();

潜在的消息映射条目如下：

映射条目	在以下情况下发送到父级...
ON_BN_CLICKED	用户单击某个按钮。
ON_BN_DOUBLECLICKED	用户双击某个按钮。

如果从对话框资源创建 CButton 对象，则在用户关闭对话框时会自动销毁 CButton 对象。

如果在窗口中创建 CButton 对象，可能需要销毁它。如果使用 new 函数在堆上创建 CButton 对象，则必须在该对象上调用 delete 以在用户关闭 Windows 按钮控件时将其销毁。如果在堆栈上创建 CButton 对象，或者该对象嵌入在父对话框对象中，则系统会自动销毁它。

继承层次结构

CObject

CCmdTarget

CWnd

CButton

要求

标头：afxwin.h

CButton::CButton

构造 CButton 对象。

CButton();

示例

// Declare a button object.
CButton myButton;

CButton::Create

创建 Windows 按钮控件并将其附加到 CButton 对象。

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

参数

lpszCaption
指定按钮控件的文本。

dwStyle
指定按钮控件的样式。将按钮样式的任意组合应用于按钮。

rect
指定按钮控件的大小和位置。它可以是 CRect 对象或 RECT 结构。

pParentWnd
指定按钮控件的父窗口，通常为 CDialog。不得为 NULL。

nID
指定按钮控件的 ID。

返回值

如果成功，则不为 0；否则为 0。

备注

请分两步构造 CButton 对象。首先调用构造函数，然后调用 Create，这会创建 Windows 按钮控件并将其附加到 CButton 对象。

如果指定了 WS_VISIBLE 样式，则 Windows 会向按钮控件发送激活和显示按钮所需的所有消息。

将以下窗口样式应用于按钮控件：

WS_CHILD（始终使用）
WS_VISIBLE（经常使用）
很少 WS_DISABLED
WS_GROUP（将控件分组）
WS_TABSTOP（在 Tab 键顺序中包含按钮）

示例

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

当所有者绘制的按钮的视觉外观发生变化时由框架调用。

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

参数

lpDrawItemStruct
指向 DRAWITEMSTRUCT 结构的长指针。结构包含有关要绘制的项以及所需绘制类型的信息。

备注

为所有者绘制的按钮设置了 BS_OWNERDRAW 样式。重写此成员函数以实现所有者绘制的 CButton 对象的绘制。在此成员函数终止之前，应用程序应还原为 lpDrawItemStruct 中提供的显示上下文选择的所有图形设备接口 (GDI) 对象。

另请参阅 BS_ 样式值。

示例

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

调用此成员函数可获取先前使用 SetBitmap 设置的与按钮关联的位图的句柄。

HBITMAP GetBitmap() const;

返回值

位图的图柄。如果先前未指定位图，则返回 NULL。

示例

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

检索有关按钮控件样式的信息。

UINT GetButtonStyle() const;

返回值

返回此 CButton 对象的按钮样式。此函数仅返回 BS_ 样式值，而不返回任何其他窗口样式。

示例

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

检索单选按钮或复选框的选中状态。

int GetCheck() const;

返回值

使用 BS_AUTOCHECKBOX、BS_AUTORADIOBUTTON、BS_AUTO3STATE、BS_CHECKBOX、BS_RADIOBUTTON 或 BS_3STATE 样式创建的按钮控件的返回值是以下值之一：

值	含义
BST_UNCHECKED	按钮状态为未选中。
BST_CHECKED	按钮状态为已选中。
BST_INDETERMINATE	按钮状态不确定（仅当按钮采用 BS_3STATE 或 BS_AUTO3STATE 样式时适用）。

如果按钮采用任何其他样式，则返回值为 BST_UNCHECKED。

示例

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

调用此成员函数可获取先前使用 SetCursor 设置的与按钮关联的光标的句柄。

HCURSOR GetCursor();

返回值

光标图像的句柄。如果先前未指定游标，则返回 NULL。

示例

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

调用此成员函数可获取先前使用 SetIcon 设置的与按钮关联的图标的句柄。

HICON GetIcon() const;

返回值

图标的图柄。如果先前未指定图标，则返回 NULL。

示例

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

检索按钮控件的理想大小。

BOOL GetIdealSize(SIZE* psize);

参数

psize
指向按钮当前大小的指针。

返回值

如果成功，则不为 0；否则为 0。

备注

此成员函数模拟 BCM_GETIDEALSIZE 消息的功能，如 Windows SDK 的按钮部分中所述。

CButton::GetImageList

调用此方法可从按钮控件中获取图像列表。

BOOL GetImageList(PBUTTON_IMAGELIST pbuttonImagelist);

参数

pbuttonImagelist
指向 CButton 对象的图像列表的指针。

返回值

如果成功，则不为 0；否则为 0。

注解

此成员函数模拟 BCM_GETIMAGELIST 消息的功能，如 Windows SDK 的按钮部分中所述。

CButton::GetNote

检索与当前命令链接控件关联的注释文本。

CString GetNote() const;

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

参数

lpszNote
[out] 指向缓冲区的指针，调用方负责分配和解除分配。如果返回值为 TRUE，则缓冲区包含与当前命令链接控件关联的注释文本；否则缓冲区未更改。

cchNote
[in, out] 指向无符号整数变量的指针。调用此方法时，变量包含 lpszNote 参数指定的缓冲区大小。当此方法返回时，如果返回值为 TRUE，则变量包含与当前命令链接控件关联的注释的大小。如果返回值为 FALSE，则变量包含缓冲区大小，需要达到此大小才能包含注释。

返回值

在第一个重载中，返回包含与当前命令链接控件关联的注释文本的 CString 对象。

- 或者 -

在第二个重载中，如果此方法成功，则返回 TRUE；否则返回 FALSE。

注解

仅对按钮样式为 BS_COMMANDLINK 或 BS_DEFCOMMANDLINK 的控件使用此方法。

此方法发送 BCM_GETNOTE 消息，如 Windows SDK 中所述。

CButton::GetNoteLength

检索当前命令链接控件的注释文本的长度。

UINT GetNoteLength() const;

返回值

当前命令链接控件的注释文本的长度，以 16 位 Unicode 字符表示。

备注

仅对按钮样式为 BS_COMMANDLINK 或 BS_DEFCOMMANDLINK 的控件使用此方法。

此方法发送 BCM_GETNOTELENGTH 消息，如 Windows SDK 中所述。

CButton::GetSplitGlyph

检索与当前拆分按钮控件关联的字形。

TCHAR GetSplitGlyph() const;

返回值

与当前拆分按钮控件关联的字形字符。

备注

字形是采用特定字体的字符的物理表示形式。例如，可以使用 Unicode 复选标记字符 (U+2713) 的字形来装饰拆分按钮控件。

仅对按钮样式为 BS_SPLITBUTTON 或 BS_DEFSPLITBUTTON 的控件使用此方法。

此方法使用 BCSIF_GLYPH 标志初始化 BUTTON_SPLITINFO 结构的 mask 成员，然后在 Windows SDK 中所述的 BCM_GETSPLITINFO 消息中发送该结构。当消息函数返回时，此方法从该结构的 himlGlyph 成员中检索字形。

CButton::GetSplitImageList

检索当前拆分按钮控件的图像列表。

CImageList* GetSplitImageList() const;

返回值

指向 CImageList 对象的指针。

注解

仅对按钮样式为 BS_SPLITBUTTON 或 BS_DEFSPLITBUTTON 的控件使用此方法。

此方法使用 BCSIF_IMAGE 标志初始化 BUTTON_SPLITINFO 结构的 mask 成员，然后在 Windows SDK 中所述的 BCM_GETSPLITINFO 消息中发送该结构。当消息函数返回时，此方法从该结构的 himlGlyph 成员中检索图像列表。

CButton::GetSplitInfo

检索用于确定 Windows 如何绘制当前拆分按钮控件的参数。

BOOL GetSplitInfo(PBUTTON_SPLITINFO pInfo) const;

参数

pInfo
[out] 指向 BUTTON_SPLITINFO 结构的指针，该结构接收有关当前拆分按钮控件的信息。调用方负责分配结构。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

备注

仅对按钮样式为 BS_SPLITBUTTON 或 BS_DEFSPLITBUTTON 的控件使用此方法。

此方法发送 BCM_GETSPLITINFO 消息，如 Windows SDK 中所述。

CButton::GetSplitSize

检索当前拆分按钮控件的下拉组件的边框。

BOOL GetSplitSize(LPSIZE pSize) const;

参数

pSize
[out] 指向接收矩形说明的 SIZE 结构的指针。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

备注

仅对按钮样式为 BS_SPLITBUTTON 或 BS_DEFSPLITBUTTON 的控件使用此方法。

当拆分按钮控件展开时，它可以显示下拉组件，例如列表控件或页导航控件。此方法检索包含下拉组件的边框。

此方法使用 BCSIF_SIZE 标志初始化 BUTTON_SPLITINFO 结构的 mask 成员，然后在 Windows SDK 中所述的 BCM_GETSPLITINFO 消息中发送该结构。当消息函数返回时，此方法从该结构的 size 成员中检索边框。

CButton::GetSplitStyle

检索用于定义当前拆分按钮控件的拆分按钮样式。

UINT GetSplitStyle() const;

返回值

拆分按钮样式的按位组合。有关详细信息，请参阅 BUTTON_SPLITINFO 结构的 uSplitStyle 成员。

注解

仅对按钮样式为 BS_SPLITBUTTON 或 BS_DEFSPLITBUTTON 的控件使用此方法。

拆分按钮样式指定 Windows 绘制的拆分按钮图标的对齐方式、纵横比和图形格式。

此方法使用 BCSIF_STYLE 标志初始化 BUTTON_SPLITINFO 结构的 mask 成员，然后在 Windows SDK 中所述的 BCM_GETSPLITINFO 消息中发送该结构。当消息函数返回时，此方法从该结构的 uSplitStyle 成员中拆分按钮样式。

CButton::GetState

检索按钮控件的状态。

UINT GetState() const;

返回值

一个位字段，其中包含指示按钮控件当前状态的值组合。下表列出了可能的值。

按钮状态	值	说明
BST_UNCHECKED	0x0000	初始状态。
BST_CHECKED	0x0001	按钮控件已选中。
BST_INDETERMINATE	0x0002	状态不确定（仅当按钮控件有三种状态时才可能出现这种状态）。
BST_PUSHED	0x0004	按钮控件已按下。
BST_FOCUS	0x0008	按钮控件具有焦点。

注解

使用 BS_3STATE 或 BS_AUTO3STATE 按钮样式的按钮控件会创建一个复选框，该复选框具有称作“不确定状态”的第三种状态。不确定状态指示复选框既未选中，也未取消选中。

示例

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

调用此方法可获取 CButton 对象的文本边距。

BOOL GetTextMargin(RECT* pmargin);

参数

pmargin
指向 CButton 对象的文本边距的指针。

返回值

返回文本边距。如果成功，则不为 0；否则为 0。

备注

此成员函数模拟 BCM_GETTEXTMARGIN 消息的功能，如 Windows SDK 的按钮部分中所述。

CButton::SetBitmap

调用此成员函数可将新位图与按钮相关联。

HBITMAP SetBitmap(HBITMAP hBitmap);

参数

hBitmap
位图的句柄。

返回值

先前与按钮关联的位图的句柄。

备注

位图将自动放置在按钮的正面，默认会居中。如果位图对于按钮而言太大，它的任何一侧将被剪裁掉。可以选择其他对齐选项，包括：

BS_TOP
BS_LEFT
BS_RIGHT
BS_CENTER
BS_BOTTOM
BS_VCENTER

与为每个按钮使用四个位图的 CBitmapButton 不同，SetBitmap 仅为每个按钮使用一个位图。按下按钮时，位图显示为向右下方移动。

你需要负责在处理完位图后将其释放。

示例

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

更改按钮的样式。

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

参数

nStyle
指定按钮样式。

bRedraw
指定是否要重绘按钮。如果使用非零值，则重绘按钮。如果使用 0 值，则不重绘按钮。默认会重绘按钮。

备注

使用 GetButtonStyle 成员函数检索按钮样式。整个按钮样式的低位字是按钮特定的样式。

示例

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

设置或重置单选按钮或复选框的选中状态。

void SetCheck(int nCheck);

参数

nCheck
指定选中状态。此参数可以是以下项之一：

值	含义
BST_UNCHECKED	将按钮状态设置为未选中。
BST_CHECKED	将按钮状态设置为已选中。
BST_INDETERMINATE	将按钮状态设置为不确定。仅当按钮采用 BS_3STATE 或 BS_AUTO3STATE 样式时，才能使用此值。

注解

此成员函数对按钮不起作用。

示例

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

调用此成员函数可将新光标与按钮相关联。

HCURSOR SetCursor(HCURSOR hCursor);

参数

hCursor
光标的句柄。

返回值

先前与按钮关联的光标的句柄。

备注

光标将自动放置在按钮的正面，默认会居中。如果光标对于按钮而言太大，它的任何一侧将被剪裁掉。可以选择其他对齐选项，包括：

BS_TOP
BS_LEFT
BS_RIGHT
BS_CENTER
BS_BOTTOM
BS_VCENTER

与为每个按钮使用四个位图的 CBitmapButton 不同，SetCursor 仅为每个按钮使用一个光标。按下按钮时，光标显示为向右下方移动。

示例

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

设置当前拆分按钮控件的下拉状态。

BOOL SetDropDownState(BOOL fDropDown);

参数

fDropDown
[in] 若要设置 BST_DROPDOWNPUSHED 状态，则为 TRUE；否则为 FALSE。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

备注

拆分按钮控件的样式为 BS_SPLITBUTTON 或 BS_DEFSPLITBUTTON，由一个按钮及其右侧的下拉箭头组成。有关详细信息，请参阅按钮样式。通常，当用户单击下拉箭头时会设置下拉状态。使用此方法能够以编程方式设置控件的下拉状态。绘制的下拉箭头带有阴影，以指示状态。

此方法发送 BCM_SETDROPDOWNSTATE 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_splitButton，该变量用于以编程方式访问拆分按钮控件。以下示例中使用了此变量。

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

以下代码示例设置拆分按钮控件的状态，以指示下拉箭头已按下。

/* 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

将当前按钮控件的状态设置为 elevation required，只有这样，控件才会显示提升的安全图标。

BOOL SetElevationRequired(BOOL fElevationRequired);

参数

fElevationRequired
[in] 若要设置 elevation required 状态，则为 TRUE；否则为 FALSE。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

备注

如果按钮或命令链接控件需要提升的安全权限才能执行操作，请将控件设置为 elevation required 状态。随后，Windows 将在控件上显示用户帐户控制 (UAC) 盾牌图标。有关详细信息，请参阅用户帐户控制。

此方法发送 BCM_SETSHIELD 消息，如 Windows SDK 中所述。

CButton::SetIcon

调用此成员函数可将新图标与按钮相关联。

HICON SetIcon(HICON hIcon);

参数

hIcon
图标的句柄。

返回值

先前与按钮关联的图标的句柄。

备注

图标将自动放置在按钮的正面，默认会居中。如果图标对于按钮而言太大，它的任何一侧将被剪裁掉。可以选择其他对齐选项，包括：

BS_TOP
BS_LEFT
BS_RIGHT
BS_CENTER
BS_BOTTOM
BS_VCENTER

与为每个按钮使用四个位图的 CBitmapButton 不同，SetIcon 仅为每个按钮使用一个图标。按下按钮时，图标显示为向右下方移动。

示例

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

调用此方法可设置 CButton 对象的图像列表。

BOOL SetImageList(PBUTTON_IMAGELIST pbuttonImagelist);

参数

pbuttonImagelist
指向新图像列表的指针。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

此成员函数模拟 BCM_SETIMAGELIST 消息的功能，如 Windows SDK 的按钮部分中所述。

CButton::SetNote

设置当前命令链接控件的注释文本。

BOOL SetNote(LPCTSTR lpszNote);

参数

lpszNote
[in] 指向 Unicode 字符串的指针，该字符串设置为命令链接控件的注释文本。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

备注

仅对按钮样式为 BS_COMMANDLINK 或 BS_DEFCOMMANDLINK 的控件使用此方法。

此方法发送 BCM_SETNOTE 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_cmdLink，该变量用于以编程方式访问命令链接控件。以下示例中使用了此变量。

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

以下代码示例设置命令链接控件的注释文本。

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

CButton::SetSplitGlyph

将指定的字形与当前拆分按钮控件相关联。

BOOL SetSplitGlyph(TCHAR chGlyph);

参数

chGlyph
[in] 一个字符，指定用作拆分按钮下拉箭头的字形。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

备注

仅对采用按钮样式 BS_SPLITBUTTON 或 BS_DEFSPLITBUTTON 的控件使用此方法。

字形是采用特定字体的字符的物理表示形式。 chGlyph 参数不用作字形，而是用于从一组系统定义的字形中选择一种字形。默认下拉箭头字形由字符“6”指定，类似于 Unicode 字符 BLACK DOWN-POINTING TRIANGLE (U+25BC)。

此方法使用 BCSIF_GLYPH 标志初始化 BUTTON_SPLITINFO 结构的 mask 成员，并使用 chGlyph 参数初始化 himlGlyph 成员，然后在 Windows SDK 中所述的 BCM_GETSPLITINFO 消息中发送该结构。

CButton::SetSplitImageList

将图像列表与当前拆分按钮控件相关联。

BOOL SetSplitImageList(CImageList* pSplitImageList);

参数

pSplitImageList
[in] 指向要分配到当前拆分按钮控件的 CImageList 对象的指针。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

备注

仅对按钮样式为 BS_SPLITBUTTON 或 BS_DEFSPLITBUTTON 的控件使用此方法。

此方法使用 BCSIF_IMAGE 标志初始化 BUTTON_SPLITINFO 结构的 mask 成员，并使用 pSplitImageList 参数初始化 himlGlyph 成员，然后在 Windows SDK 中所述的 BCM_GETSPLITINFO 消息中发送该结构。

CButton::SetSplitInfo

指定用于确定 Windows 如何绘制当前拆分按钮控件的参数。

BOOL SetSplitInfo(PBUTTON_SPLITINFO pInfo);

参数

pInfo
[in] 指向用于定义当前拆分按钮控件的 BUTTON_SPLITINFO 结构的指针。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

备注

仅对按钮样式为 BS_SPLITBUTTON 或 BS_DEFSPLITBUTTON 的控件使用此方法。

此方法发送 BCM_SETSPLITINFO 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_splitButton，该变量用于以编程方式访问拆分按钮控件。

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

以下代码示例更改拆分按钮下拉箭头使用的字形。该示例将默认的向下三角形字形替换为向上三角形字形。显示的字形取决于在 BUTTON_SPLITINFO 结构的 himlGlyph 成员中指定的字符。向下三角形字形由字符“6”指定，向上三角形字形由字符“5”指定。有关比较，请参阅便捷方法 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

设置当前拆分按钮控件的下拉组件的边框。

BOOL SetSplitSize(LPSIZE pSize);

参数

pSize
[in] 指向描述边框的 SIZE 结构的指针。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

备注

仅对按钮样式为 BS_SPLITBUTTON 或 BS_DEFSPLITBUTTON 的控件使用此方法。

当拆分按钮控件展开时，它可以显示下拉组件，例如列表控件或页导航控件。此方法指定包含下拉组件的边框的大小。

此方法使用 BCSIF_SIZE 标志初始化 BUTTON_SPLITINFO 结构的 mask 成员，并使用 pSize 参数初始化 size 成员，然后在 Windows SDK 中所述的 BCM_GETSPLITINFO 消息中发送该结构。

示例

第一个代码示例定义变量 m_splitButton，该变量用于以编程方式访问拆分按钮控件。以下示例中使用了此变量。

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

以下代码示例将拆分按钮下拉箭头的大小加倍。

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

设置当前拆分按钮控件的样式。

BOOL SetSplitStyle(UINT uSplitStyle);

参数

uSplitStyle
[in] 拆分按钮样式的按位组合。有关详细信息，请参阅 BUTTON_SPLITINFO 结构的 uSplitStyle 成员。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

备注

仅对按钮样式为 BS_SPLITBUTTON 或 BS_DEFSPLITBUTTON 的控件使用此方法。

拆分按钮样式指定 Windows 绘制的拆分按钮图标的对齐方式、纵横比和图形格式。有关详细信息，请参阅 BUTTON_SPLITINFO 结构的 uSplitStyle 成员。

此方法使用 BCSIF_STYLE 标志初始化 BUTTON_SPLITINFO 结构的 mask 成员，并使用 uSplitStyle 参数初始化 uSplitStyle 成员，然后在 Windows SDK 中所述的 BCM_GETSPLITINFO 消息中发送该结构。

示例

第一个代码示例定义变量 m_splitButton，该变量用于以编程方式访问拆分按钮控件。

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

以下代码示例设置拆分按钮下拉箭头的样式。 BCSS_ALIGNLEFT 样式在按钮左侧显示箭头，BCSS_STRETCH 样式在调整按钮大小时保留下拉箭头的比例。

/* 
    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

设置按钮控件是否突出显示。

void SetState(BOOL bHighlight);

参数

bHighlight
指定按钮是否突出显示。如果使用非零值，则突出显示按钮；如果使用 0 值，则取消任何突出显示。

备注

突出显示会影响按钮控件的外部结构。它对单选按钮或复选框的选中状态不起作用。

当用户单击并按住鼠标左键时，按钮控件将自动突出显示。当用户松开鼠标按钮时，将取消突出显示。

示例

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

调用此方法可设置 CButton 对象的文本边距。

BOOL SetTextMargin(RECT* pmargin);

参数

pmargin
指向新文本边距的指针。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

此成员函数模拟 BCM_SETTEXTMARGIN 消息的功能，如 Windows SDK 的按钮部分中所述。

另请参阅

CWnd 类
 层次结构图
 CWnd 类
 CComboBox 类
 CEdit 类
 CListBox 类
 CScrollBar 类
 CStatic 类
 CBitmapButton 类
 CDialog 类

通过

CButton 类

语法

成员

公共构造函数

公共方法

注解

继承层次结构

要求

CButton::CButton

示例

CButton::Create

参数

返回值

备注

示例

CButton::DrawItem

参数

备注

示例

CButton::GetBitmap

返回值

示例

CButton::GetButtonStyle

返回值

示例

CButton::GetCheck

返回值

示例

CButton::GetCursor

返回值

示例

CButton::GetIcon

返回值

示例

CButton::GetIdealSize

参数

返回值

备注

CButton::GetImageList

参数

返回值

注解

CButton::GetNote

参数

返回值

注解

CButton::GetNoteLength

返回值

备注

CButton::GetSplitGlyph

返回值

备注

CButton::GetSplitImageList

返回值

注解

CButton::GetSplitInfo

参数

返回值

备注

CButton::GetSplitSize

参数

返回值

备注

CButton::GetSplitStyle

返回值

注解

CButton::GetState

返回值

注解

示例

CButton::GetTextMargin

参数

返回值

备注

CButton::SetBitmap

参数

返回值

备注

示例