`CScrollBar` 类

项目
06/16/2023

提供 Windows 滚动条控件功能。

语法

class CScrollBar : public CWnd

成员

公共构造函数

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

公共方法

名称	描述
`CScrollBar::Create`	创建 Windows 滚动条并将其附加到 `CScrollBar` 对象。
`CScrollBar::EnableScrollBar`	启用或禁用滚动条的一个或两个箭头。
`CScrollBar::GetScrollBarInfo`	使用 `SCROLLBARINFO` 结构检索有关滚动条的信息。
`CScrollBar::GetScrollInfo`	检索有关滚动条的信息。
`CScrollBar::GetScrollLimit`	检索滚动条的限制
`CScrollBar::GetScrollPos`	检索滚动框的当前位置。
`CScrollBar::GetScrollRange`	检索给定滚动条的当前最小和最大滚动条位置。
`CScrollBar::SetScrollInfo`	设置有关滚动条的信息。
`CScrollBar::SetScrollPos`	设置滚动框的当前位置。
`CScrollBar::SetScrollRange`	设置给定滚动条的最小和最大位置值。
`CScrollBar::ShowScrollBar`	显示或隐藏滚动条。

备注

请通过两个步骤创建滚动条控件。首先调用构造函数 CScrollBar 以构造 CScrollBar 对象，然后调用 Create 成员函数以创建 Windows 滚动条控件，并将其附加到 CScrollBar 对象。

如果在对话框中创建 CScrollBar 对象（通过对话框资源），则在用户关闭对话框时会自动销毁 CScrollBar。

如果在窗口中创建 CScrollBar 对象，可能还需要销毁该对象。

如果在堆栈上创建 CScrollBar 对象，则会自动销毁该对象。如果使用 new 函数在堆上创建 CScrollBar 对象，则必须在该对象上调用 delete，以便在用户终止 Windows 滚动条时将其销毁。

如果在 CScrollBar 对象中分配任何内存，请替代 CScrollBar 析构函数以释放分配。

有关使用 CScrollBar 的相关信息，请参阅控件。

继承层次结构

CObject

CCmdTarget

CWnd

CScrollBar

要求

标头：afxwin.h

`CScrollBar::Create`

创建 Windows 滚动条并将其附加到 CScrollBar 对象。

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

参数

dwStyle
指定滚动条的样式。将滚动条样式的任意组合应用于滚动条。

rect
指定滚动条的大小和位置。可以是 RECT 结构或 CRect 对象。

pParentWnd
指定滚动条的父窗口（通常是 CDialog 对象）。不得为 NULL。

nID
滚动条的控制 ID。

返回值

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

备注

请分两步构造 CScrollBar 对象。首先，调用构造函数来构造 CScrollBar 对象；然后调用 Create 来创建并初始化关联的 Windows 滚动条并将其附加到 CScrollBar 对象。

将以下窗口样式应用于滚动条：

WS_CHILD：始终
WS_VISIBLE：通常
WS_DISABLED 很少
WS_GROUP 对控件进行分组

示例

// Example 1:
// Create a horizontal CScrollBar control as a child window of CMyDialog
// class (a CDialog-derived class). The scroll bar is NOT visible until the
// call ShowScrollBar() is made. m_ScrollBarHorz is of type CScrollBar class,
// and it is a member variable in CMyDialog class.
VERIFY(m_ScrollBarHorz.Create(SBS_HORZ | SBS_TOPALIGN | WS_CHILD,
                              CRect(5, 5, 100, 30), this, IDC_SCROLLBARCTRL));

m_ScrollBarHorz.ShowScrollBar();

// Example 2:
// Create a vertical CScrollBar control as a child window of CMyDialog
// class (a CDialog-derived class). m_ScrollBarVert is of type CScrollBar
// class, and it is a member variable in CMyDialog class.
VERIFY(m_ScrollBarVert.Create(SBS_VERT | SBS_LEFTALIGN | WS_CHILD |
                                  WS_VISIBLE,
                              CRect(5, 30, 30, 130), this, IDC_SCROLLBARCTRL));

`CScrollBar::CScrollBar`

构造 CScrollBar 对象。

CScrollBar();

备注

构造对象后，调用 Create 成员函数以创建并初始化 Windows 滚动条。

示例

CScrollBar m_ScrollBarHorz;

`CScrollBar::EnableScrollBar`

启用或禁用滚动条的一个或两个箭头。

BOOL EnableScrollBar(UINT nArrowFlags = ESB_ENABLE_BOTH);

参数

nArrowFlags
指定是启用还是禁用滚动箭头，以及启用或禁用哪些箭头。此参数可能是以下值之一：

ESB_ENABLE_BOTH：启用滚动条的两个箭头。
ESB_DISABLE_LTUP 禁用水平滚动条的向左箭头或垂直滚动条的向上箭头。
ESB_DISABLE_RTDN 禁用水平滚动条的向右箭头或垂直滚动条的向下箭头。
ESB_DISABLE_BOTH 禁用滚动条的两个箭头。

返回值

如果箭头已按指定启用或禁用，则为非零值；否则为 0，指示箭头已处于请求的状态或发生错误。

示例

请参阅 CScrollBar::SetScrollRange 的示例。

`CScrollBar::GetScrollBarInfo`

检索 SCROLLBARINFO 结构维护的有关滚动条的信息。

BOOL GetScrollBarInfo(PSCROLLBARINFO pScrollInfo) const;

参数

pScrollInfo
指向 SCROLLBARINFO 结构的指针。

返回值

成功时返回 TRUE，失败时返回 FALSE。

注解

此成员函数模拟 SBM_SCROLLBARINFO 消息的功能，如 Windows SDK 中所述。

`CScrollBar::GetScrollInfo`

检索 SCROLLINFO 结构维护的有关滚动条的信息。

BOOL GetScrollInfo(
    LPSCROLLINFO lpScrollInfo,
    UINT nMask = SIF_ALL);

参数

lpScrollInfo
指向 SCROLLINFO 结构的指针。有关此结构的详细信息，请参阅 Windows SDK。

nMask
指定要检索的滚动条参数。典型用法 SIF_ALL 指定 SIF_PAGE、SIF_POS、SIF_TRACKPOS 和 SIF_RANGE 的一个组合。有关 nMask 值的详细信息，请参阅 SCROLLINFO。

返回值

如果消息检索了任何值，则返回值为 TRUE。否则为 FALSE。

注解

GetScrollInfo 允许应用程序使用 32 位滚动位置。

SCROLLINFO 结构包含有关滚动条的信息，包括最小和最大滚动位置、页面大小以及滚动框 (Thumb) 的位置。若要详细了解如何更改结构默认值，请参阅 Windows SDK 中的 SCROLLINFO 结构主题。

指示滚动条位置的 MFC Windows 消息处理程序 CWnd::OnHScroll 和 CWnd::OnVScroll 仅提供 16 位位置数据。 GetScrollInfo 和 SetScrollInfo 提供 32 位滚动条位置数据。因此，应用程序可以在处理 CWnd::OnHScroll 或 CWnd::OnVScroll 以获取 32 位滚动条位置数据时调用 GetScrollInfo。

示例

请参阅 CWnd::OnHScroll 的示例。

`CScrollBar::GetScrollLimit`

检索滚动条的最大滚动位置。

int GetScrollLimit();

返回值

如果成功，则指定滚动条的最大位置；否则指定 0。

示例

请参阅 CWnd::OnHScroll 的示例。

`CScrollBar::GetScrollPos`

检索滚动框的当前位置。

int GetScrollPos() const;

返回值

如果成功，则指定滚动框的当前位置；否则指定 0。

备注

当前位置是一个相对值，取决于当前滚动范围。例如，如果滚动范围为 100 到 200，并且滚动框位于滚动条中间，则当前位置为 150。

示例

请参阅 CWnd::OnHScroll 的示例。

`CScrollBar::GetScrollRange`

将给定滚动条的当前最小和最大滚动条位置复制到 lpMinPos 和 lpMaxPos 指定的位置。

void GetScrollRange(
    LPINT lpMinPos,
    LPINT lpMaxPos) const;

参数

lpMinPos
指向要接收最小位置的整数变量。

lpMaxPos
指向要接收最大位置的整数变量。

备注

滚动条控件的默认范围为空（两个值均为 0）。

示例

请参阅 CWnd::OnHScroll 的示例。

`CScrollBar::SetScrollInfo`

设置 SCROLLINFO 结构维护的有关滚动条的信息。

BOOL SetScrollInfo(
    LPSCROLLINFO lpScrollInfo,
    BOOL bRedraw = TRUE);

参数

lpScrollInfo
指向 SCROLLINFO 结构的指针。

bRedraw
指定是否应重新绘制滚动条以反映新信息。如果 bRedraw 为 TRUE，则重绘滚动条。如果为 FALSE，则不重新绘制。默认情况下，滚动条会重新绘制。

返回值

如果成功，则返回值为 TRUE。否则为 FALSE。

注解

必须提供 SCROLLINFO 结构参数所需的值，包括标志值。

示例

// Set SCROLLINFO for the scroll bar. m_ScrollBarHorz is of type
// CScrollBar class, and it is a member variable in CMyDialog class.
SCROLLINFO info;
info.cbSize = sizeof(SCROLLINFO);
info.fMask = SIF_ALL;
info.nMin = 0;
info.nMax = 10;
info.nPage = 2;
info.nPos = 5;
info.nTrackPos = 2;
m_ScrollBarHorz.SetScrollInfo(&info);

`CScrollBar::SetScrollPos`

将滚动框的当前位置设置为 nPos 指定的位置，并在已指定该位置的情况下重新绘制滚动条以反映新位置。

int SetScrollPos(
    int nPos,
    BOOL bRedraw = TRUE);

参数

nPos
指定滚动框的新位置。它必须在滚动范围内。

bRedraw
指定是否应重绘滚动条以反映新位置。如果 bRedraw 为 TRUE，则重绘滚动条。如果为 FALSE，则不重新绘制。默认情况下，滚动条会重新绘制。

返回值

如果成功，则指定滚动框的上一位置；否则指定 0。

注解

每当通过对另一个函数的后续调用重新绘制滚动条时，请将 bRedraw 设置为 FALSE，以免在短时间内重新绘制滚动条两次。

示例

请参阅 CScrollBar::SetScrollRange 的示例。

`CScrollBar::SetScrollRange`

设置给定滚动条的最小和最大位置值。

void SetScrollRange(
    int nMinPos,
    int nMaxPos,
    BOOL bRedraw = TRUE);

参数

nMinPos
指定最小滚动位置。

nMaxPos
指定最大滚动位置。

bRedraw
指定是否应重新绘制滚动条以反映更改。如果 bRedraw 为 TRUE，则重新绘制滚动条；如果为 FALSE，则不重新绘制。默认重新绘制。

备注

将 nMinPos 和 nMaxPos 设置为 0 可隐藏标准滚动条。

在处理滚动条通知消息时，请勿调用此函数来隐藏滚动条。

如果在调用 SetScrollPos 成员函数后立刻调用 SetScrollRange，请将 SetScrollPos 中的 bRedraw 设置为 0，以防止将滚动条重新绘制两次。

通过 nMinPos 和 nMaxPos 指定的值之间的差异不得大于 32,767。滚动条控件的默认范围为空（nMinPos 和 nMaxPos 均为 0）。

示例

// Sets minimum (0) and maximum (10) position values for the
// CScrollBar control. m_ScrollBarVert is of type CScrollBar class,
// and it is a member variable in CMyDialog class.
m_ScrollBarVert.SetScrollRange(0, 10);

// Set the position of the scroll box.
m_ScrollBarVert.SetScrollPos(5);

// Disable the down arrow of the scroll bar. By default, both arrows
// are enabled.
m_ScrollBarVert.EnableScrollBar(ESB_DISABLE_DOWN);

`CScrollBar::ShowScrollBar`

显示或隐藏滚动条。

void ShowScrollBar(BOOL bShow = TRUE);

参数

bShow
指定滚动条是显示还是隐藏。如果此参数为 TRUE，则显示滚动条；否则隐藏滚动条。

注解

在处理滚动条通知消息时，应用程序不应调用此函数来隐藏滚动条。

示例

请参阅 CScrollBar::Create 的示例。

另请参阅

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

通过

CScrollBar 类

语法

成员

公共构造函数

公共方法

备注

继承层次结构

要求

CScrollBar::Create

参数

返回值

备注

示例

CScrollBar::CScrollBar

备注

示例

CScrollBar::EnableScrollBar

参数

返回值

示例

CScrollBar::GetScrollBarInfo

参数

返回值

注解

CScrollBar::GetScrollInfo

参数

返回值

注解

示例

CScrollBar::GetScrollLimit

返回值

示例

CScrollBar::GetScrollPos

返回值

备注

示例

CScrollBar::GetScrollRange

参数

备注

示例

CScrollBar::SetScrollInfo

参数

返回值

注解

示例

CScrollBar::SetScrollPos

参数

返回值

注解

示例

CScrollBar::SetScrollRange

参数

备注

示例

CScrollBar::ShowScrollBar

参数

注解

示例

另请参阅

反馈

其他资源

`CScrollBar` 类

`CScrollBar::Create`

`CScrollBar::CScrollBar`

`CScrollBar::EnableScrollBar`

`CScrollBar::GetScrollBarInfo`

`CScrollBar::GetScrollInfo`

`CScrollBar::GetScrollLimit`

`CScrollBar::GetScrollPos`

`CScrollBar::GetScrollRange`

`CScrollBar::SetScrollInfo`

`CScrollBar::SetScrollPos`

`CScrollBar::SetScrollRange`

`CScrollBar::ShowScrollBar`