CSpinButtonCtrl 类

项目
10/16/2023

提供 Windows 公共数值调节钮控件的功能。

语法

class CSpinButtonCtrl : public CWnd

成员

公共构造函数

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

公共方法

名称	描述
CSpinButtonCtrl::Create	创建数值调节钮控件并将其附加到 `CSpinButtonCtrl` 对象。
CSpinButtonCtrl::CreateEx	创建具有指定 Windows 扩展样式的数值调节钮控件，并将其附加到 `CSpinButtonCtrl` 对象。
CSpinButtonCtrl::GetAccel	检索数值调节钮控件的加速信息。
CSpinButtonCtrl::GetBase	检索数值调节钮控件的当前基数。
CSpinButtonCtrl::GetBuddy	检索指向当前合作者窗口的指针。
CSpinButtonCtrl::GetPos	检索数值调节钮控件的当前位置。
CSpinButtonCtrl::GetRange	检索数值调节钮控件的上限和下限（范围）。
CSpinButtonCtrl::SetAccel	设置数值调节钮控件的加速度。
CSpinButtonCtrl::SetBase	设置数值调节钮控件的基数。
CSpinButtonCtrl::SetBuddy	设置数值调节钮控件的合作者窗口。
CSpinButtonCtrl::SetPos	设置控件的当前位置。
CSpinButtonCtrl::SetRange	设置数值调节钮控件的上限和下限（范围）。

备注

“数值调节钮控件”（也称为 up-down 控件）是一对箭头按钮，用户可以单击这些按钮来递增或递减值，如滚动位置或配套控件中显示的数字。与数值调节钮控件关联的值称为其当前位置。数值调节钮控件经常与配套控件一起使用，被称为“合作者窗口”。

此控件（以及 CSpinButtonCtrl 类）仅适用于在 Windows 95/98 和 Windows NT 版本 3.51 及更高版本下运行的程序。

对于用户而言，数值调节钮控件及其合作者窗口通常看起来像单个控件。可以指定数值调节钮控件自动将自己定位在其合作者窗口旁边，并自动将合作者窗口的标题设置为其当前位置。可以将数值调节钮控件与编辑控件结合使用，以提示用户输入数字。

单击向上箭头将当前位置向最大值移动，单击向下箭头将当前位置向最小值移动。默认情况下，最小值为 100，最大值为 0。每当最小设置大于最大设置时（例如，当使用默认设置时），单击向上箭头会减小位置值，单击向下箭头会增加位置值。

不使用合作者窗口功能的数值调节钮控件用作简化后的滚动条。例如，选项卡控件有时显示一个数值调节钮控件，以使用户能够将其他选项卡滚动到视图中。

有关使用 CSpinButtonCtrl 的详细信息，请参阅控件和使用 CSpinButtonCtrl。

继承层次结构

CObject

CCmdTarget

CWnd

CSpinButtonCtrl

要求

标头： afxcmn.h

CSpinButtonCtrl::Create

创建数值调节钮控件并将其附加到 CSpinButtonCtrl 对象。

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

参数

dwStyle
指定数值调节钮控件的样式。将数值调节钮控件样式的任意组合应用于控件。这些样式在 Windows SDK 的 Up-Down 控件样式中介绍。

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

pParentWnd
指向数值调节钮控件的父窗口（通常为 CDialog）的指针。不得为 NULL。

nID
指定数值调节钮控件的 ID。

返回值

如果初始化成功，则返回非零值；否则返回 0。

注解

通过两个步骤构造 CSpinButtonCtrl 对象。首先，调用构造函数，然后调用 Create，这将创建数值调节钮控件并将其附加到 CSpinButtonCtrl 对象。

若要创建具有扩展窗口样式的数值调节钮控件，请调用 CSpinButtonCtrl::CreateEx 而不是 Create。

CSpinButtonCtrl::CreateEx

创建一个控件（子窗口）并将其与 CSpinButtonCtrl 对象相关联。

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

参数

dwExStyle
指定要创建的控件的扩展样式。有关扩展 Windows 样式的列表，请参阅 Windows SDK 中 CreateWindowEx 的 dwExStyle 参数。

dwStyle
指定数值调节钮控件的样式。将数值调节钮控件样式的任意组合应用于控件。这些样式在 Windows SDK 的 Up-Down 控件样式中介绍。

rect
对 RECT 结构的引用，该结构描述了要在客户端坐标 pParentWnd 中创建的窗口的大小和位置。

pParentWnd
指向作为控件父级的窗口的指针。

nID
控件的子窗口 ID。

返回值

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

注解

使用 CreateEx 而不是 Create 来应用由 Windows 扩展样式前言 WS_EX_ 指定的扩展 Windows 样式。

CSpinButtonCtrl::CSpinButtonCtrl

构造 CSpinButtonCtrl 对象。

CSpinButtonCtrl();

CSpinButtonCtrl::GetAccel

检索数值调节钮控件的加速信息。

UINT GetAccel(
    int nAccel,
    UDACCEL* pAccel) const;

参数

nAccel
pAccel 指定的数组中的元素数。

pAccel
指向接收加速信息的 UDACCEL 结构的数组的指针。

返回值

检索到的加速器结构数。

CSpinButtonCtrl::GetBase

检索数值调节钮控件的当前基数。

UINT GetBase() const;

返回值

当前基值。

CSpinButtonCtrl::GetBuddy

检索指向当前合作者窗口的指针。

CWnd* GetBuddy() const;

返回值

指向当前合作者窗口的指针。

CSpinButtonCtrl::GetPos

检索数值调节钮控件的当前位置。

int GetPos() const;  int GetPos32(LPBOOL lpbError = NULL) const;

参数

lpbError
指向布尔值的指针，如果成功检索该值，则将其设置为零；如果发生错误，则设置为非零。如果此参数设置为 NULL，则不会报告错误。

返回值

第一个版本返回低位字中的 16 位当前位置。如果发生错误，则高位字为非零。

第二个版本返回 32 位位置。

注解

当它处理返回的值时，控件会根据合作者窗口的标题更新其当前位置。如果没有合作者窗口，或者如果标题指定了无效或超出范围的值，则该控件将返回错误。

CSpinButtonCtrl::GetRange

检索数值调节钮控件的上限和下限（范围）。

DWORD GetRange() const;

void GetRange(
    int& lower,
    int& upper) const;

void GetRange32(
    int& lower,
    int &upper) const;

参数

lower
对接收控件下限的整数的引用。

upper
对接收控件上限的整数的引用。

返回值

第一个版本返回包含上限和下限的 32 位值。低位字是控件的上限，高位字是下限。

注解

成员函数 GetRange32 以 32 位整数的形式检索数字显示数值调节钮控件的范围。

CSpinButtonCtrl::SetAccel

设置数值调节钮控件的加速度。

BOOL SetAccel(
    int nAccel,
    UDACCEL* pAccel);

参数

nAccel
由 pAccel 指定的 UDACCEL 结构的数量。

pAccel
指向包含加速度信息的 UDACCEL 结构数组的指针。元素应根据 nSec 成员按升序排序。

返回值

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

CSpinButtonCtrl::SetBase

设置数值调节钮控件的基数。

int SetBase(int nBase);

参数

nBase
控件的新基值。十进制可以是 10，十六进制可以是 16。

返回值

如果成功，则为上一个基值；如果给定无效基数，则为零。

注解

基值确定合作者窗口是以十进制数字还是十六进制数字显示数字。十六进制数字总是无符号的；十进制数有符号。

CSpinButtonCtrl::SetBuddy

设置数值调节钮控件的合作者窗口。

CWnd* SetBuddy(CWnd* pWndBuddy);

参数

pWndBuddy
指向新合作者窗口的指针。

返回值

指向上一个合作者窗口的指针。

备注

数值调节钮控件几乎总是与显示某些内容的另一个窗口（如编辑控件）相关联。此另一个窗口称为数值调节钮控件的“合作者”。

CSpinButtonCtrl::SetPos

设置数值调节钮控件的当前位置。

int SetPos(int nPos);
int SetPos32(int nPos);

参数

nPos
控件的新位置。此值必须在控件的上限和下限指定的范围内。

返回值

上一个位置（SetPos 为 16 位精度，SetPos32 为 32 位精度）。

备注

SetPos32 设置 32 位位置。

CSpinButtonCtrl::SetRange

设置数值调节钮控件的上限和下限（范围）。

void SetRange(
    short nLower,
    short nUpper);

void SetRange32(
    int nLower,
    int nUpper);

参数

nLower 和 nUpper
控件的上限和下限。对于 SetRange，任何限制都不能大于 UD_MAXVAL 或小于 UD_MINVAL；此外，两个限制之间的差异不能超过 UD_MAXVAL。 SetRange32 对限制没有限制；使用任何整数。

注解

成员函数 SetRange32 设置数值调节钮控件的 32 位范围。

注意

默认情况下，数值调节钮的范围最大设置为零 (0)，最小设置为 100。由于最大值小于最小值，因此单击上箭头将降低位置，单击下箭头将增高位置。使用 CSpinButtonCtrl::SetRange 调整这些值。

另请参阅

MFC 示例 CMNCTRL2
CWnd 类
 层次结构图
 CSliderCtrl 类