CPagerCtrl 类

项目
06/16/2023

CPagerCtrl 类用于包装 Windows 页导航控件，可以滚动此控件以查看所包含的不适合包含窗口的窗口。

语法

class CPagerCtrl : public CWnd

成员

公共构造函数

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

公共方法

名称	描述
CPagerCtrl::Create	创建具有指定样式的页导航控件，并将其附加到当前 `CPagerCtrl` 对象。
CPagerCtrl::CreateEx	创建具有指定扩展样式的页导航控件，并将其附加到当前 `CPagerCtrl` 对象。
CPagerCtrl::ForwardMouse	启用或禁用将 WM_MOUSEMOVE 消息转发到当前页导航控件中包含的窗口。
CPagerCtrl::GetBkColor	检索当前页导航控件的背景色。
CPagerCtrl::GetBorder	检索当前页导航控件的边框大小。
CPagerCtrl::GetButtonSize	检索当前页导航控件的按钮大小。
CPagerCtrl::GetButtonState	检索当前页导航控件中指定按钮的状态。
CPagerCtrl::GetDropTarget	检索当前页导航控件的 IDropTarget 接口。
CPagerCtrl::GetScrollPos	检索当前页导航控件的滚动位置。
CPagerCtrl::IsButtonDepressed	指示当前页导航控件的指定按钮是否处于 `pressed` 状态。
CPagerCtrl::IsButtonGrayed	指示当前页导航控件的指定按钮是否处于 `grayed` 状态。
CPagerCtrl::IsButtonHot	指示当前页导航控件的指定按钮是否处于 `hot` 状态。
CPagerCtrl::IsButtonInvisible	指示当前页导航控件的指定按钮是否处于 `invisible` 状态。
CPagerCtrl::IsButtonNormal	指示当前页导航控件的指定按钮是否处于 `normal` 状态。
CPagerCtrl::RecalcSize	使当前页导航控件重新计算包含窗口的大小。
CPagerCtrl::SetBkColor	设置当前页导航控件的背景色。
CPagerCtrl::SetBorder	设置当前页导航控件的边框大小。
CPagerCtrl::SetButtonSize	设置当前页导航控件的按钮大小。
CPagerCtrl::SetChild	设置当前页导航控件的包含窗口。
CPagerCtrl::SetScrollPos	设置当前页导航控件的滚动位置。

注解

页导航控件是一个窗口，其中包含另一个线型窗口，该窗口大于包含它的窗口，让你能够将所包含的窗口滚动到视图中。页导航控件显示两个滚动按钮，这些按钮在所包含的窗口滚动到最远端时自动消失，否则会再次出现。可以创建水平或垂直滚动的页导航控件。

例如，如果应用程序使用一个不够宽的工具栏来显示其所有项，则可以将工具栏分配给页导航控件，并且用户将能够向左或向右滚动工具栏以访问所有项。 Microsoft Internet Explorer 版本 4.0（commctrl.dll 版本 4.71）引入了页导航控件。

CPagerCtrl 类派生自 CWnd 类。有关详细信息和页导航控件的插图，请参阅页导航控件。

继承层次结构

CObject

CCmdTarget

CWnd

CPagerCtrl

要求

标头： afxcmn.h

CPagerCtrl::CPagerCtrl

构造 CPagerCtrl 对象。

CPagerCtrl();

备注

使用 CPagerCtrl::Create 或 CPagerCtrl::CreateEx 方法创建页导航控件并将其附加到 CPagerCtrl 对象。

CPagerCtrl::Create

创建具有指定样式的页导航控件，并将其附加到当前 CPagerCtrl 对象。

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

参数

dwStyle
[in] 要应用于控件的窗口样式和页导航控件样式的按位组合（或）。

rect
[in] 对 RECT 结构的引用，该结构包含客户端坐标中控件的位置和大小。

pParentWnd
[in] 指向 CWnd 对象（控件的父窗口）的指针。此参数不能为 NULL。

nID
[in] 控件的 ID。

返回值

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

注解

若要创建页导航控件，请声明 CPagerCtrl 变量，然后对该变量调用 CPagerCtrl::Create 或 CPagerCtrl::CreateEx 方法。

示例

以下示例创建页导航控件，然后使用 CPagerCtrl::SetChild 方法将很长的按钮控件与页导航控件相关联。然后，该示例使用 CPagerCtrl::SetButtonSize 方法将页导航控件的高度设置为 20 像素，使用 CPagerCtrl::SetBorder 方法将边框粗细设置为 1 像素。

// Initialize the dropdown menu of the splitbutton control.
m_splitButton.SetDropDownMenu(IDR_MENU1, 0);

// Create the pager control.
BOOL nRet;
CRect rect;
GetClientRect(&rect);
nRet = m_pager.Create(
    (WS_VISIBLE | WS_CHILD | PGS_HORZ),
    CRect(rect.Width() / 4, 5, (rect.Width() * 3) / 4, 55),
    this,
    IDC_PAGER1);

m_pager.GetClientRect(&rect);
nRet = m_button.Create(
    _T("This is a very, very long button. 012345678901234567890"),
    (WS_VISIBLE | WS_CHILD), // Do not use CCS_NORESIZE.
    CRect(0, 0, rect.Width(), 30),
    &m_pager, IDC_BUTTON1);

m_pager.SetChild(m_button.m_hWnd);
m_pager.SetButtonSize(20);
m_pager.SetBorder(1);

CPagerCtrl::CreateEx

创建具有指定扩展样式的页导航控件，并将其附加到当前 CPagerCtrl 对象。

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

参数

dwExStyle
[in] 要应用于控件的扩展样式的按位组合。有关详细信息，请参阅 CreateWindowEx 函数的 dwExStyle 参数。

dwStyle
[in] 要应用于控件的窗口样式和页导航控件样式的按位组合（或）。

rect
[in] 对 RECT 结构的引用，该结构包含客户端坐标中控件的位置和大小。

pParentWnd
[in] 指向 CWnd 对象（控件的父窗口）的指针。此参数不能为 NULL。

nID
[in] 控件的 ID。

返回值

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

备注

若要创建页导航控件，请声明 CPagerCtrl 变量，然后对该变量调用 CPagerCtrl::Create 或 CPagerCtrl::CreateEx 方法。

CPagerCtrl::ForwardMouse

启用或禁用将 WM_MOUSEMOVE 消息转发到当前页导航控件中包含的窗口。

void ForwardMouse(BOOL bForward);

参数

bForward
[in] 若要转发鼠标消息，则为 TRUE，否则为 FALSE。

备注

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

CPagerCtrl::GetBorder

检索当前页导航控件的边框大小。

int GetBorder() const;

返回值

以像素为单位的当前边框大小。

备注

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

示例

以下示例使用 CPagerCtrl::GetBorder 方法检索页导航控件边框的粗细。

void CCSplitButton_s2Dlg::OnXBorder()
{
   int borderSize = m_pager.GetBorder();
   CString str;
   str.Format(_T("The border is %d pixel(s) thick."), borderSize);
   MessageBox(str);
}

CPagerCtrl::GetBkColor

检索当前页导航控件的背景色。

COLORREF GetBkColor() const;

返回值

一个 COLORREF 值，该值包含页导航控件的当前背景色。

备注

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

示例

以下示例使用 CPagerCtrl::SetBkColor 方法将页导航控件的背景色设置为红色，使用 CPagerCtrl::GetBkColor 方法确认已进行更改。

void CCSplitButton_s2Dlg::OnXColor()
{
   COLORREF originalColor;
   //  Set color to red.
   originalColor = m_pager.SetBkColor(RGB(255, 0, 0));
   if (m_pager.GetBkColor() != RGB(255, 0, 0))
   {
      MessageBox(_T("Control did not return RED as the previous color."));
   }
   // The following statement is one way to restore the color.
   // m_pager.SetBkColor( originalColor );
}

CPagerCtrl::GetButtonSize

检索当前页导航控件的按钮大小。

int GetButtonSize() const;

返回值

以像素为单位的当前按钮大小。

备注

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

如果页导航控件具有 PGS_HORZ 样式，则按钮大小决定了页导航按钮的宽度，如果页导航控件具有 PGS_VERT 样式，则按钮大小决定了页导航按钮的高度。有关详细信息，请参阅页导航控件样式。

CPagerCtrl::GetButtonState

检索当前页导航控件中指定滚动按钮的状态。

DWORD GetButtonState(int iButton) const;

参数

iButton
[in] 指示已检索其状态的按钮。如果页导航控件样式为 PGS_HORZ，请为左侧按钮指定 PGB_TOPORLEFT，并为右侧按钮指定 PGB_BOTTOMORRIGHT。如果页导航控件样式 PGS_VERT，请为顶部按钮指定 PGB_TOPORLEFT，并为底部按钮指定 PGB_BOTTOMORRIGHT。有关详细信息，请参阅页导航控件样式。

返回值

iButton 参数指定的按钮的状态。状态为 PGF_INVISIBLE、PGF_NORMAL、PGF_GRAYED、PGF_DEPRESSED 或 PGF_HOT。有关详细信息，请参阅 PGM_GETBUTTONSTATE 消息的“返回值”部分。

注解

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

CPagerCtrl::GetDropTarget

检索当前页导航控件的 IDropTarget 接口。

IDropTarget* GetDropTarget() const;

返回值

指向当前页导航控件的 IDropTarget 接口的指针。

备注

IDropTarget 是你实现用于支持应用程序中的拖放操作的接口之一。

此方法将发送 PGM_GETDROPTARGET 消息，如 Windows SDK 中所述。此方法的调用方负责在不再需要接口时调用 IDropTarget 接口的 Release 成员。

CPagerCtrl::GetScrollPos

检索当前页导航控件的滚动位置。

int GetScrollPos() const;

返回值

以像素为单位的当前滚动位置。

备注

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

示例

以下示例使用 CPagerCtrl::GetScrollPos 方法检索页导航控件的当前滚动位置。如果页导航控件尚未滚动到零（最左侧的位置），则该示例使用 CPagerCtrl::SetScrollPos 方法将滚动位置设置为零。

void CCSplitButton_s2Dlg::OnXScrollposition()
{
   int pos;
   CString str;
   pos = m_pager.GetScrollPos();
   if (pos != 0)
      m_pager.SetScrollPos(0);
   str.Format(_T("Old position = %d; new position = 0"), pos);
   MessageBox(str);
}

CPagerCtrl::IsButtonDepressed

指示当前页导航控件的指定滚动按钮是否处于按下状态。

BOOL IsButtonDepressed(int iButton) const;

参数

返回值

如果指定的按钮处于按下状态，则为 TRUE；否则为 FALSE。

备注

此方法将发送 PGM_GETBUTTONSTATE 消息，如 Windows SDK 中所述。然后，它会测试返回的状态是否为 PGF_DEPRESSED。有关详细信息，请参阅 PGM_GETBUTTONSTATE 消息的“返回值”部分。

CPagerCtrl::IsButtonGrayed

指示当前页导航控件的指定滚动按钮是否处于灰显状态。

BOOL IsButtonGrayed(int iButton) const;

参数

返回值

如果指定的按钮处于灰显状态，则为 TRUE；否则为 FALSE。

备注

此方法将发送 PGM_GETBUTTONSTATE 消息，如 Windows SDK 中所述。然后，它会测试返回的状态是否为 PGF_GRAYED。有关详细信息，请参阅 PGM_GETBUTTONSTATE 消息的“返回值”部分。

CPagerCtrl::IsButtonHot

指示当前页导航控件的指定滚动按钮是否处于热状态。

BOOL IsButtonHot(int iButton) const;

参数

返回值

如果指定的按钮处于热状态，则为 TRUE；否则为 FALSE。

备注

此方法将发送 PGM_GETBUTTONSTATE 消息，如 Windows SDK 中所述。然后，它会测试返回的状态是否为 PGF_HOT。有关详细信息，请参阅 PGM_GETBUTTONSTATE 消息的“返回值”部分。

CPagerCtrl::IsButtonInvisible

指示当前页导航控件的指定滚动按钮是否处于不可见状态。

BOOL IsButtonInvisible(int iButton) const;

参数

返回值

如果指定的按钮处于不可见状态，则为 TRUE；否则为 FALSE。

备注

所包含的窗口滚动到最远端时，Windows 会隐藏处于特定方向的滚动按钮，因为进一步单击该按钮无法将更多所包含的窗口带入视图。

此方法将发送 PGM_GETBUTTONSTATE 消息，如 Windows SDK 中所述。然后，它会测试返回的状态是否为 PGF_INVISIBLE。有关详细信息，请参阅 PGM_GETBUTTONSTATE 消息的“返回值”部分。

示例

以下示例使用 CPagerCtrl::IsButtonInvisible 方法来确定页导航控件的左右滚动按钮是否可见。


void CCSplitButton_s2Dlg::OnXIsbuttoninvisible()
{
   BOOL bLeft = m_pager.IsButtonInvisible(PGB_TOPORLEFT);
   BOOL bRight = m_pager.IsButtonInvisible(PGB_BOTTOMORRIGHT);
   CString str;
   str.Format(_T("The left button is%s visible; the right button is%s visible."),
              (bLeft ? _T(" not") : _T("")),
              (bRight ? _T(" not") : _T("")));
   MessageBox(str);
}

CPagerCtrl::IsButtonNormal

指示当前页导航控件的指定滚动按钮是否处于正常状态。

BOOL IsButtonNormal(int iButton) const;

参数

返回值

如果指定的按钮处于正常状态，则为 TRUE；否则为 FALSE。

注解

此方法将发送 PGM_GETBUTTONSTATE 消息，如 Windows SDK 中所述。然后，它会测试返回的状态是否为 PGF_NORMAL。有关详细信息，请参阅 PGM_GETBUTTONSTATE 消息的“返回值”部分。

CPagerCtrl::RecalcSize

使当前页导航控件重新计算包含窗口的大小。

void RecalcSize();

备注

此方法将发送 PGM_RECALCSIZE 消息，如 Windows SDK 中所述。因此，页导航控件发送 PGN_CALCSIZE 通知，以获取包含窗口的可滚动尺寸。

示例 1

以下示例使用 CPagerCtrl::RecalcSize 方法请求当前页导航控件重新计算其大小。

void CCSplitButton_s2Dlg::OnXRecalcsize()
{
   // If the child control changes size, call RecalcSize() to change
   // the size of the pager control accordingly.
   m_pager.RecalcSize();
   MessageBox(_T("The pager control size has been recalculated."));
}

示例 2

以下示例使用消息反射使页导航控件能够重新计算自己的大小，而不是要求控件的父对话执行计算。该示例从 CPagerCtrl 类派生 MyPagerCtrl 类，然后使用消息映射将 PGN_CALCSIZE 通知与 OnCalcsize 通知处理程序相关联。在此示例中，通知处理程序将页导航控件的宽度和高度设置为固定值。

BEGIN_MESSAGE_MAP(CMyPagerCtrl, CPagerCtrl)
ON_NOTIFY_REFLECT(PGN_CALCSIZE, &CMyPagerCtrl::OnCalcSize)
END_MESSAGE_MAP()

// CMyPagerCtrl message handlers
void CMyPagerCtrl::OnCalcSize(NMHDR *code, LRESULT *param)
{
   // If the control contained in the pager control changes size, use this
   // handler to change the size of the pager control accordingly.

   LPNMPGCALCSIZE tmp = (LPNMPGCALCSIZE)code;
   *param = 0;
   tmp->iWidth = 500;
   tmp->iHeight = 50;
}

CPagerCtrl::SetBkColor

设置当前页导航控件的背景色。

COLORREF SetBkColor(COLORREF clrBk);

参数

clrBk
[in] 一个 COLORREF 值，该值包含页导航控件的新背景色。

返回值

一个 COLORREF 值，该值包含页导航控件的上一背景色。

备注

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

示例

以下示例使用 CPagerCtrl::SetBkColor 方法将页导航控件的背景色设置为红色，使用 CPagerCtrl::GetBkColor 方法确认已进行更改。

void CCSplitButton_s2Dlg::OnXColor()
{
   COLORREF originalColor;
   //  Set color to red.
   originalColor = m_pager.SetBkColor(RGB(255, 0, 0));
   if (m_pager.GetBkColor() != RGB(255, 0, 0))
   {
      MessageBox(_T("Control did not return RED as the previous color."));
   }
   // The following statement is one way to restore the color.
   // m_pager.SetBkColor( originalColor );
}

CPagerCtrl::SetBorder

设置当前页导航控件的边框大小。

int SetBorder(int iBorder);

参数

iBorder
[in] 以像素为单位的新边框大小。如果 iBorder 参数为负数，则边框大小设置为零。

返回值

以像素为单位的上一个边框大小。

注解

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

示例

// Initialize the dropdown menu of the splitbutton control.
m_splitButton.SetDropDownMenu(IDR_MENU1, 0);

// Create the pager control.
BOOL nRet;
CRect rect;
GetClientRect(&rect);
nRet = m_pager.Create(
    (WS_VISIBLE | WS_CHILD | PGS_HORZ),
    CRect(rect.Width() / 4, 5, (rect.Width() * 3) / 4, 55),
    this,
    IDC_PAGER1);

m_pager.GetClientRect(&rect);
nRet = m_button.Create(
    _T("This is a very, very long button. 012345678901234567890"),
    (WS_VISIBLE | WS_CHILD), // Do not use CCS_NORESIZE.
    CRect(0, 0, rect.Width(), 30),
    &m_pager, IDC_BUTTON1);

m_pager.SetChild(m_button.m_hWnd);
m_pager.SetButtonSize(20);
m_pager.SetBorder(1);

CPagerCtrl::SetButtonSize

设置当前页导航控件的按钮大小。

int SetButtonSize(int iButtonSize);

参数

iButtonSize
[in] 以像素为单位的新按钮大小。

返回值

以像素为单位的上一个按钮大小。

注解

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

如果页导航控件具有 PGS_HORZ 样式，则按钮大小决定了页导航按钮的宽度，如果页导航控件具有 PGS_VERT 样式，则按钮大小决定了页导航按钮的高度。默认按钮大小为滚动条宽度的四分之三，最小按钮大小为 12 像素。有关详细信息，请参阅页导航控件样式。

示例

// Initialize the dropdown menu of the splitbutton control.
m_splitButton.SetDropDownMenu(IDR_MENU1, 0);

// Create the pager control.
BOOL nRet;
CRect rect;
GetClientRect(&rect);
nRet = m_pager.Create(
    (WS_VISIBLE | WS_CHILD | PGS_HORZ),
    CRect(rect.Width() / 4, 5, (rect.Width() * 3) / 4, 55),
    this,
    IDC_PAGER1);

m_pager.GetClientRect(&rect);
nRet = m_button.Create(
    _T("This is a very, very long button. 012345678901234567890"),
    (WS_VISIBLE | WS_CHILD), // Do not use CCS_NORESIZE.
    CRect(0, 0, rect.Width(), 30),
    &m_pager, IDC_BUTTON1);

m_pager.SetChild(m_button.m_hWnd);
m_pager.SetButtonSize(20);
m_pager.SetBorder(1);

CPagerCtrl::SetChild

设置当前页导航控件的包含窗口。

void SetChild(HWND hwndChild);

参数

hwndChild
[in] 要包含的窗口的句柄。

备注

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

此方法不会更改所包含窗口的父级；它只为用于滚动的页导航控件分配窗口句柄。在大多数情况下，所包含的窗口将是页导航控件的子窗口。

示例

// Initialize the dropdown menu of the splitbutton control.
m_splitButton.SetDropDownMenu(IDR_MENU1, 0);

// Create the pager control.
BOOL nRet;
CRect rect;
GetClientRect(&rect);
nRet = m_pager.Create(
    (WS_VISIBLE | WS_CHILD | PGS_HORZ),
    CRect(rect.Width() / 4, 5, (rect.Width() * 3) / 4, 55),
    this,
    IDC_PAGER1);

m_pager.GetClientRect(&rect);
nRet = m_button.Create(
    _T("This is a very, very long button. 012345678901234567890"),
    (WS_VISIBLE | WS_CHILD), // Do not use CCS_NORESIZE.
    CRect(0, 0, rect.Width(), 30),
    &m_pager, IDC_BUTTON1);

m_pager.SetChild(m_button.m_hWnd);
m_pager.SetButtonSize(20);
m_pager.SetBorder(1);

CPagerCtrl::SetScrollPos

设置当前页导航控件的滚动位置。

void SetScrollPos(int iPos);

参数

iPos
[in] 以像素为单位的新滚动位置。

备注

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

另请参阅

CPagerCtrl 类
 层次结构图
 页导航控件

通过