CPagerCtrl Class

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CPagerCtrl Class.

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

Parameter	Description
[in] `dwStyle`	A bitwise combination (OR) of window styles and pager control styles to be applied to the control.
[in] `rect`	A reference to a RECT structure that contains the position and size of the control in client coordinates.
[in] `pParentWnd`	A pointer to a CWnd object that is the parent window of the control. This parameter cannot be `NULL`.
[in] `nID`	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

Parameter	Description
[in] `dwExStyle`	A bitwise combination of extended styles to be applied to the control. For more information, see the `dwExStyle` parameter of the CreateWindowEx function.
[in] `dwStyle`	A bitwise combination (OR) of window styles and pager control styles to be applied to the control.
[in] `rect`	A reference to a RECT structure that contains the position and size of the control in client coordinates.
[in] `pParentWnd`	A pointer to a CWnd object that is the parent window of the control. This parameter cannot be `NULL`.
[in] `nID`	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

Parameter	Description
[in] `bForward`	`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.

CPagerCtrl::GetButtonState

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

DWORD GetButtonState(int iButton) const;

Parameters

Parameter	Description
[in] `iButton`	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

Parameter	Description
[in] `iButton`	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

Parameter	Description
[in] `iButton`	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

Parameter	Description
[in] `iButton`	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

Parameter	Description
[in] `iButton`	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

Parameter	Description
[in] `iButton`	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

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

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

Parameter	Description
[in] `clrBk`	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

Parameter	Description
[in] `iBorder`	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

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

Parameter	Description
[in] `iButtonSize`	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

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

Parameter	Description
[in] `hwndChild`	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

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

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

Remarks

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

Share via

CPagerCtrl Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

CPagerCtrl::CPagerCtrl

Remarks

CPagerCtrl::Create

Parameters

Return Value

Remarks

Example

CPagerCtrl::CreateEx

Parameters

Return Value

Remarks

CPagerCtrl::ForwardMouse

Parameters

Remarks

CPagerCtrl::GetBorder

Return Value

Remarks

Example

CPagerCtrl::GetBkColor

Return Value

Remarks

Example

CPagerCtrl::GetButtonSize

Return Value

Remarks

CPagerCtrl::GetButtonState

Parameters

Return Value

Remarks

CPagerCtrl::GetDropTarget

Return Value

Remarks

CPagerCtrl::GetScrollPos

Return Value

Remarks

Example

CPagerCtrl::IsButtonDepressed

Parameters

Return Value

Remarks

CPagerCtrl::IsButtonGrayed

Parameters

Return Value

Remarks

CPagerCtrl::IsButtonHot

Parameters

Return Value

Remarks

CPagerCtrl::IsButtonInvisible

Parameters

Return Value

Remarks

Example

CPagerCtrl::IsButtonNormal

Parameters

Return Value

Remarks

CPagerCtrl::RecalcSize

Remarks

Example

Example

CPagerCtrl::SetBkColor

Parameters

Return Value

Remarks

Example

CPagerCtrl::SetBorder

Parameters

Return Value

Remarks

Example