| description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | ||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CPagerCtrl Class |
CPagerCtrl Class |
11/04/2016 |
|
|
65ac58dd-4f5e-4b7e-b15c-e0d435a7e884 |
The CPagerCtrl class wraps the Windows pager control, which can scroll into view a contained window that does not fit the containing window.
class CPagerCtrl : public CWnd
| Name | Description |
|---|---|
| CPagerCtrl::CPagerCtrl | Constructs a CPagerCtrl object. |
| 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. |
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.
CPagerCtrl
Header: afxcmn.h
Constructs a CPagerCtrl object.
CPagerCtrl();
Use the CPagerCtrl::Create or CPagerCtrl::CreateEx method to create a pager control and attach it to the CPagerCtrl object.
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);
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.
TRUE if this method is successful; otherwise, FALSE.
To create a pager control, declare a CPagerCtrl variable, then call the CPagerCtrl::Create or CPagerCtrl::CreateEx method on that variable.
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.
[!code-cppNVC_MFC_CSplitButton_s2#1]
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);
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.
TRUE if this method is successful; otherwise, FALSE.
To create a pager control, declare a CPagerCtrl variable, then call the CPagerCtrl::Create or CPagerCtrl::CreateEx method on that variable.
Enables or disables forwarding WM_MOUSEMOVE messages to the window that is contained in the current pager control.
void ForwardMouse(BOOL bForward);bForward
[in] TRUE to forward mouse messages, or FALSE to not forward mouse messages.
This method sends the PGM_FORWARDMOUSE message, which is described in the Windows SDK.
Retrieves the border size of the current pager control.
int GetBorder() const;
The current border size, measured in pixels.
This method sends the PGM_GETBORDER message, which is described in the Windows SDK.
The following example uses the CPagerCtrl::GetBorder method to retrieve the thickness of the pager control's border.
[!code-cppNVC_MFC_CSplitButton_s2#5]
Retrieves the background color of the current pager control.
COLORREF GetBkColor() const;
A COLORREF value that contains the current background color of the pager control.
This method sends the PGM_GETBKCOLOR message, which is described in the Windows SDK.
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.
[!code-cppNVC_MFC_CSplitButton_s2#4]
Retrieves the button size of the current pager control.
int GetButtonSize() const;
The current button size, measured in pixels.
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.
Retrieves the state of the specified scroll button in the current pager control.
DWORD GetButtonState(int iButton) const;
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.
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.
This method sends the PGM_GETBUTTONSTATE message, which is described in the Windows SDK.
Retrieves the IDropTarget interface for the current pager control.
IDropTarget* GetDropTarget() const;
A pointer to the IDropTarget interface for the current pager control.
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.
Retrieves the scroll position of the current pager control.
int GetScrollPos() const;
The current scroll position, measured in pixels.
This method sends the PGM_GETPOS message, which is described in the Windows SDK.
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.
[!code-cppNVC_MFC_CSplitButton_s2#7]
Indicates whether the specified scroll button of the current pager control is in pressed state.
BOOL IsButtonDepressed(int iButton) const;
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.
TRUE if the specified button is in pressed state; otherwise, FALSE.
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.
Indicates whether the specified scroll button of the current pager control is in grayed state.
BOOL IsButtonGrayed(int iButton) const;
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.
TRUE if the specified button is in grayed state; otherwise, FALSE.
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.
Indicates whether the specified scroll button of the current pager control is in hot state.
BOOL IsButtonHot(int iButton) const;
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.
TRUE if the specified button is in hot state; otherwise, FALSE.
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.
Indicates whether the specified scroll button of the current pager control is in invisible state.
BOOL IsButtonInvisible(int iButton) const;
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.
TRUE if the specified button is in invisible state; otherwise, FALSE.
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.
The following example uses the CPagerCtrl::IsButtonInvisible method to determine whether the pager control's left and right scroll buttons are visible.
[!code-cppNVC_MFC_CSplitButton_s2#6]
Indicates whether the specified scroll button of the current pager control is in normal state.
BOOL IsButtonNormal(int iButton) const;
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.
TRUE if the specified button is in normal state; otherwise, FALSE.
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.
Causes the current pager control to recalculate the size of the contained window.
void RecalcSize();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.
The following example uses the CPagerCtrl::RecalcSize method to request the current pager control to recalculate its size.
[!code-cppNVC_MFC_CSplitButton_s2#3]
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.
[!code-cppNVC_MFC_CSplitButton_s2#8]
Sets the background color of the current pager control.
COLORREF SetBkColor(COLORREF clrBk);
clrBk
[in] A COLORREF value that contains the new background color of the pager control.
A COLORREF value that contains the previous background color of the pager control.
This method sends the PGM_SETBKCOLOR message, which is described in the Windows SDK.
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.
[!code-cppNVC_MFC_CSplitButton_s2#4]
Sets the border size of the current pager control.
int SetBorder(int iBorder);
iBorder
[in] The new border size, measured in pixels. If the iBorder parameter is negative, the border size is set to zero.
The previous border size, measured in pixels.
This method sends the PGM_SETBORDER message, which is described in the Windows SDK.
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.
[!code-cppNVC_MFC_CSplitButton_s2#1]
Sets the button size of the current pager control.
int SetButtonSize(int iButtonSize);
iButtonSize
[in] The new button size, measured in pixels.
The previous button size, measured in pixels.
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.
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.
[!code-cppNVC_MFC_CSplitButton_s2#1]
Sets the contained window for the current pager control.
void SetChild(HWND hwndChild);hwndChild
[in] Handle to the window to be contained.
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.
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.
[!code-cppNVC_MFC_CSplitButton_s2#1]
Sets the scroll position of the current pager control.
void SetScrollPos(int iPos);iPos
[in] The new scroll position, measured in pixels.
This method sends the PGM_SETPOS message, which is described in the Windows SDK.