Muokkaa

Jaa

CPagerCtrl Class

  • Artikkeli

The CPagerCtrl class wraps the Windows pager control, which can scroll into view a contained window that does not fit the containing window.

Syntax

class CPagerCtrl : public CWnd

Members

Public Constructors

Name Description
CPagerCtrl::CPagerCtrl Constructs a CPagerCtrl object.

Public Methods

Name Description
CPagerCtrl::Create Creates a pager control with specified styles and attaches it to the current CPagerCtrl object.
CPagerCtrl::CreateEx Creates a pager control with specified extended styles and attaches it to the current CPagerCtrl object.
CPagerCtrl::ForwardMouse Enables or disables forwarding WM_MOUSEMOVE messages to the window that is contained in the current pager control.
CPagerCtrl::GetBkColor Retrieves the background color of the current pager control.
CPagerCtrl::GetBorder Retrieves the border size of the current pager control.
CPagerCtrl::GetButtonSize Retrieves the button size of the current pager control.
CPagerCtrl::GetButtonState Retrieves the state of the specified button in the current pager control.
CPagerCtrl::GetDropTarget Retrieves the IDropTarget interface for the current pager control.
CPagerCtrl::GetScrollPos Retrieves the scroll position of the current pager control.
CPagerCtrl::IsButtonDepressed Indicates whether the specified button of the current pager control is in pressed state.
CPagerCtrl::IsButtonGrayed Indicates whether the specified button of the current pager control is in grayed state.
CPagerCtrl::IsButtonHot Indicates whether the specified button of the current pager control is in hot state.
CPagerCtrl::IsButtonInvisible Indicates whether the specified button of the current pager control is in invisible state.
CPagerCtrl::IsButtonNormal Indicates whether the specified button of the current pager control is in normal state.
CPagerCtrl::RecalcSize Causes the current pager control to recalculate the size of the contained window.
CPagerCtrl::SetBkColor Sets the background color of the current pager control.
CPagerCtrl::SetBorder Sets the border size of the current pager control.
CPagerCtrl::SetButtonSize Sets the button size of the current pager control.
CPagerCtrl::SetChild Sets the contained window for the current pager control.
CPagerCtrl::SetScrollPos Sets the scroll position of the current pager control.

Remarks

A pager control is a window that contains another window that is linear and larger than the containing window, and enables you to scroll the contained window into view. The pager control displays two scroll buttons that automatically disappear when the contained window is scrolled to its farthest extent, and reappear otherwise. You can create a pager control that scrolls either horizontally or vertically.

For example, if your application has a toolbar that is not wide enough to show all of its items, you can assign the toolbar to a pager control and users will be able to scroll the toolbar to the left or right to access all of the items. Microsoft Internet Explorer Version 4.0 (commctrl.dll version 4.71) introduces the pager control.

The CPagerCtrl class is derived from the CWnd class. For more information and an illustration of a pager control, see Pager Controls.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CPagerCtrl

Requirements

Header: afxcmn.h

CPagerCtrl::CPagerCtrl

Constructs a CPagerCtrl object.

CPagerCtrl();

Remarks

Use the CPagerCtrl::Create or CPagerCtrl::CreateEx method to create a pager control and attach it to the CPagerCtrl object.

CPagerCtrl::Create

Creates a pager control with specified styles and attaches it to the current CPagerCtrl object.

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

Parameters

dwStyle
[in] A bitwise combination (OR) of window styles and pager control styles to be applied to the control.

rect
[in] A reference to a RECT structure that contains the position and size of the control in client coordinates.

pParentWnd
[in] A pointer to a CWnd object that is the parent window of the control. This parameter cannot be NULL.

nID
[in] The ID of the control.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

To create a pager control, declare a CPagerCtrl variable, then call the CPagerCtrl::Create or CPagerCtrl::CreateEx method on that variable.

Example

The following example creates a pager control, then uses the CPagerCtrl::SetChild method to associate a very long button control with the pager control. The example then uses the CPagerCtrl::SetButtonSize method to set the height of the pager control to 20 pixels, and the CPagerCtrl::SetBorder method to set the border thickness to 1 pixel.

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

Creates a pager control with specified extended styles and attaches it to the current CPagerCtrl object.

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

Parameters

dwExStyle
[in] A bitwise combination of extended styles to be applied to the control. For more information, see the dwExStyle parameter of the CreateWindowEx function.

dwStyle
[in] A bitwise combination (OR) of window styles and pager control styles to be applied to the control.

rect
[in] A reference to a RECT structure that contains the position and size of the control in client coordinates.

pParentWnd
[in] A pointer to a CWnd object that is the parent window of the control. This parameter cannot be NULL.

nID
[in] The ID of the control.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

To create a pager control, declare a CPagerCtrl variable, then call the CPagerCtrl::Create or CPagerCtrl::CreateEx method on that variable.

CPagerCtrl::ForwardMouse

Enables or disables forwarding WM_MOUSEMOVE messages to the window that is contained in the current pager control.

void ForwardMouse(BOOL bForward);

Parameters

bForward
[in] TRUE to forward mouse messages, or FALSE to not forward mouse messages.

Remarks

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

CPagerCtrl::GetBorder

Retrieves the border size of the current pager control.

int GetBorder() const;

Return Value

The current border size, measured in pixels.

Remarks

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

Example

The following example uses the CPagerCtrl::GetBorder method to retrieve the thickness of the pager control's border.

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

Retrieves the background color of the current pager control.

COLORREF GetBkColor() const;

Return Value

A COLORREF value that contains the current background color of the pager control.

Remarks

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

Example

The following example uses the CPagerCtrl::SetBkColor method to set the background color of the pager control to red, and the CPagerCtrl::GetBkColor method to confirm that the change was made.

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

Retrieves the button size of the current pager control.

int GetButtonSize() const;

Return Value

The current button size, measured in pixels.

Remarks

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

If the pager control has the PGS_HORZ style, the button size determines the width of the pager buttons, and if the pager control has the PGS_VERT style, the button size determines the height of the pager buttons. For more information, see Pager Control Styles.

CPagerCtrl::GetButtonState

Retrieves the state of the specified scroll button in the current pager control.

DWORD GetButtonState(int iButton) const;

Parameters

iButton
[in] Indicates the button for which the state is retrieved. If the pager control style is PGS_HORZ, specify PGB_TOPORLEFT for the left button and PGB_BOTTOMORRIGHT for the right button. If the pager control style is PGS_VERT, specify PGB_TOPORLEFT for the top button and PGB_BOTTOMORRIGHT for the bottom button. For more information, see Pager Control Styles.

Return Value

The state of the button specified by the iButton parameter. The state is either PGF_INVISIBLE, PGF_NORMAL, PGF_GRAYED, PGF_DEPRESSED, or PGF_HOT. For more information, see the Return Value section of the PGM_GETBUTTONSTATE message.

Remarks

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

CPagerCtrl::GetDropTarget

Retrieves the IDropTarget interface for the current pager control.

IDropTarget* GetDropTarget() const;

Return Value

A pointer to the IDropTarget interface for the current pager control.

Remarks

IDropTarget is one of the interfaces you implement to support drag-and-drop operations in your application.

This method sends the PGM_GETDROPTARGET message, which is described in the Windows SDK. The caller of this method is responsible for calling the Release member of the IDropTarget interface when the interface is no longer needed.

CPagerCtrl::GetScrollPos

Retrieves the scroll position of the current pager control.

int GetScrollPos() const;

Return Value

The current scroll position, measured in pixels.

Remarks

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

Example

The following example uses the CPagerCtrl::GetScrollPos method to retrieve the current scroll position of the pager control. If the pager control is not already scrolled to zero, the leftmost position, the example uses the CPagerCtrl::SetScrollPos method to set the scroll position to zero.

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

Indicates whether the specified scroll button of the current pager control is in pressed state.

BOOL IsButtonDepressed(int iButton) const;

Parameters

iButton
[in] Indicates the button for which the state is retrieved. If the pager control style is PGS_HORZ, specify PGB_TOPORLEFT for the left button and PGB_BOTTOMORRIGHT for the right button. If the pager control style is PGS_VERT, specify PGB_TOPORLEFT for the top button and PGB_BOTTOMORRIGHT for the bottom button. For more information, see Pager Control Styles.

Return Value

TRUE if the specified button is in pressed state; otherwise, FALSE.

Remarks

This method sends the PGM_GETBUTTONSTATE message, which is described in the Windows SDK. It then tests whether the state that is returned is PGF_DEPRESSED. For more information, see the Return Value section of the PGM_GETBUTTONSTATE message.

CPagerCtrl::IsButtonGrayed

Indicates whether the specified scroll button of the current pager control is in grayed state.

BOOL IsButtonGrayed(int iButton) const;

Parameters

iButton
[in] Indicates the button for which the state is retrieved. If the pager control style is PGS_HORZ, specify PGB_TOPORLEFT for the left button and PGB_BOTTOMORRIGHT for the right button. If the pager control style is PGS_VERT, specify PGB_TOPORLEFT for the top button and PGB_BOTTOMORRIGHT for the bottom button. For more information, see Pager Control Styles.

Return Value

TRUE if the specified button is in grayed state; otherwise, FALSE.

Remarks

This method sends the PGM_GETBUTTONSTATE message, which is described in the Windows SDK. It then tests whether the state that is returned is PGF_GRAYED. For more information, see the Return Value section of the PGM_GETBUTTONSTATE message.

CPagerCtrl::IsButtonHot

Indicates whether the specified scroll button of the current pager control is in hot state.

BOOL IsButtonHot(int iButton) const;

Parameters

iButton
[in] Indicates the button for which the state is retrieved. If the pager control style is PGS_HORZ, specify PGB_TOPORLEFT for the left button and PGB_BOTTOMORRIGHT for the right button. If the pager control style is PGS_VERT, specify PGB_TOPORLEFT for the top button and PGB_BOTTOMORRIGHT for the bottom button. For more information, see Pager Control Styles.

Return Value

TRUE if the specified button is in hot state; otherwise, FALSE.

Remarks

This method sends the PGM_GETBUTTONSTATE message, which is described in the Windows SDK. It then tests whether the state that is returned is PGF_HOT. For more information, see the Return Value section of the PGM_GETBUTTONSTATE message.

CPagerCtrl::IsButtonInvisible

Indicates whether the specified scroll button of the current pager control is in invisible state.

BOOL IsButtonInvisible(int iButton) const;

Parameters

iButton
[in] Indicates the button for which the state is retrieved. If the pager control style is PGS_HORZ, specify PGB_TOPORLEFT for the left button and PGB_BOTTOMORRIGHT for the right button. If the pager control style is PGS_VERT, specify PGB_TOPORLEFT for the top button and PGB_BOTTOMORRIGHT for the bottom button. For more information, see Pager Control Styles.

Return Value

TRUE if the specified button is in invisible state; otherwise, FALSE.

Remarks

Windows makes the scroll button in a particular direction invisible when the contained window is scrolled to its farthest extent because clicking the button further cannot bring more of the contained window into view.

This method sends the PGM_GETBUTTONSTATE message, which is described in the Windows SDK. It then tests whether the state that is returned is PGF_INVISIBLE. For more information, see the Return Value section of the PGM_GETBUTTONSTATE message.

Example

The following example uses the CPagerCtrl::IsButtonInvisible method to determine whether the pager control's left and right scroll buttons are visible.


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

Indicates whether the specified scroll button of the current pager control is in normal state.

BOOL IsButtonNormal(int iButton) const;

Parameters

iButton
[in] Indicates the button for which the state is retrieved. If the pager control style is PGS_HORZ, specify PGB_TOPORLEFT for the left button and PGB_BOTTOMORRIGHT for the right button. If the pager control style is PGS_VERT, specify PGB_TOPORLEFT for the top button and PGB_BOTTOMORRIGHT for the bottom button. For more information, see Pager Control Styles.

Return Value

TRUE if the specified button is in normal state; otherwise, FALSE.

Remarks

This method sends the PGM_GETBUTTONSTATE message, which is described in the Windows SDK. It then tests whether the state that is returned is PGF_NORMAL. For more information, see the Return Value section of the PGM_GETBUTTONSTATE message.

CPagerCtrl::RecalcSize

Causes the current pager control to recalculate the size of the contained window.

void RecalcSize();

Remarks

This method sends the PGM_RECALCSIZE message, which is described in the Windows SDK. Consequently, the pager control sends the PGN_CALCSIZE notification to obtain the scrollable dimensions of the contained window.

Example 1

The following example uses the CPagerCtrl::RecalcSize method to request the current pager control to recalculate its size.

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."));
}

Example 2

The following example uses message reflection to enable the pager control to recalculate its own size instead of requiring the control's parent dialog to perform the calculation. The example derives the MyPagerCtrl class from the CPagerCtrl class, then uses a message map to associate the PGN_CALCSIZE notification with the OnCalcsize notification handler. In this example, the notification handler sets the width and height of the pager control to fixed values.

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

Sets the background color of the current pager control.

COLORREF SetBkColor(COLORREF clrBk);

Parameters

clrBk
[in] A COLORREF value that contains the new background color of the pager control.

Return Value

A COLORREF value that contains the previous background color of the pager control.

Remarks

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

Example

The following example uses the CPagerCtrl::SetBkColor method to set the background color of the pager control to red, and the CPagerCtrl::GetBkColor method to confirm that the change was made.

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

Sets the border size of the current pager control.

int SetBorder(int iBorder);

Parameters

iBorder
[in] The new border size, measured in pixels. If the iBorder parameter is negative, the border size is set to zero.

Return Value

The previous border size, measured in pixels.

Remarks

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

Example

The following example creates a pager control, then uses the CPagerCtrl::SetChild method to associate a very long button control with the pager control. The example then uses the CPagerCtrl::SetButtonSize method to set the height of the pager control to 20 pixels, and the CPagerCtrl::SetBorder method to set the border thickness to 1 pixel.

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

Sets the button size of the current pager control.

int SetButtonSize(int iButtonSize);

Parameters

iButtonSize
[in] The new button size, measured in pixels.

Return Value

The previous button size, measured in pixels.

Remarks

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

If the pager control has the PGS_HORZ style, the button size determines the width of the pager buttons, and if the pager control has the PGS_VERT style, the button size determines the height of the pager buttons. The default button size is three-fourths of the width of the scroll bar, and the minimum button size is 12 pixels. For more information, see Pager Control Styles.

Example

The following example creates a pager control, then uses the CPagerCtrl::SetChild method to associate a very long button control with the pager control. The example then uses the CPagerCtrl::SetButtonSize method to set the height of the pager control to 20 pixels, and the CPagerCtrl::SetBorder method to set the border thickness to 1 pixel.

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

Sets the contained window for the current pager control.

void SetChild(HWND hwndChild);

Parameters

hwndChild
[in] Handle to the window to be contained.

Remarks

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

This method does not change the parent of the contained window; it only assigns a window handle to the pager control for scrolling. In most cases, the contained window will be a child window of the pager control.

Example

The following example creates a pager control, then uses the CPagerCtrl::SetChild method to associate a very long button control with the pager control. The example then uses the CPagerCtrl::SetButtonSize method to set the height of the pager control to 20 pixels, and the CPagerCtrl::SetBorder method to set the border thickness to 1 pixel.

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

Sets the scroll position of the current pager control.

void SetScrollPos(int iPos);

Parameters

iPos
[in] The new scroll position, measured in pixels.

Remarks

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

See also

CPagerCtrl Class
Hierarchy Chart
Pager Controls