
A pager control is a window container that is used with a window that does not have enough display area to show all of its content. The pager control allows the user to scroll to the area of the window that is not currently in view.
Microsoft® Internet Explorer Version 4.0 introduces the pager control. This control is useful in situations where a window does not have enough area to display a child window. 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 to the left or right to access all of the items. You can also create pager controls that scroll vertically.
A window assigned to the pager control is referred to as the contained window.
The following illustration shows a toolbar contained inside of a pager control. The pager control is displayed in red to show what areas of the control are visible.
Note The pager control is implemented in version 4.71 and later of Comctl32.dll.
This section describes how to implement the pager control in your application.
To use the pager control, you must call InitCommonControlsEx with the ICC_PAGESCROLLER_CLASSES flag set in the dwICC member of the INITCOMMONCONTROLSEX structure.
Use the CreateWindow or the CreateWindowEx API to create a pager control. The class name for the control is WC_PAGESCROLLER, which is defined in Commctrl.h. The PGS_HORZ style is used to create a horizontal pager, and the PGS_VERT style is used to create a vertical pager. Because this is a child control, the WS_CHILD style should also be used.
Once the pager control is created, you will most likely want to assign a contained window to it. If the contained window is a child window, you should make the child window a child of the pager control so that the size and position will be calculated correctly. You then assign the window to the pager control with the PGM_SETCHILD message. Be aware that this message does not actually change the parent window of the contained window; it simply assigns the contained window. If the contained window is one of the common controls, it must have the CCS_NORESIZE style to prevent the control from attempting to resize itself to the pager control's size.
At a minimum, it is necessary to process the PGN_CALCSIZE notification. If you don't process this notification and enter a value for the width or height, the scroll arrows in the pager control will not be displayed. This is because the pager control uses the width or height supplied in the PGN_CALCSIZE notification to determine the "ideal" size of the contained window.
The following example demonstrates how to process the PGN_CALCSIZE notification case. In this example, the contained window is a toolbar control that contains an unknown number of buttons at an unknown size. The example shows how to use the TB_GETMAXSIZE message to determine the size of all of the items in the toolbar. The example then places the width of all of the items into the iWidth member of the NMPGCALCSIZE structure passed to the notification.
case PGN_CALCSIZE:
{
LPNMPGCALCSIZE pCalcSize = (LPNMPGCALCSIZE)lParam;
switch(pCalcSize->dwFlag)
{
case PGF_CALCWIDTH:
{
SIZE size;
//Get the optimum width of the toolbar.
SendMessage(hwndToolbar, TB_GETMAXSIZE, 0, (LPARAM)&size);
pCalcSize->iWidth = size.cx;
}
break;
}
}
return 0;
Processing the PGN_SCROLL notification is optional. Process this notification if you need to know when a scroll action occurs, need to track the scroll position, or wish to change the scroll delta. To cancel the scroll, simply place zero in the iScroll member of the NMPGSCROLL structure passed to the notification.
The following example shows how to modify the scroll delta.
case PGN_SCROLL:
{
LPNMPGSCROLL pScroll = (LPNMPGSCROLL)lParam;
switch(pScroll->iDir)
{
case PGF_SCROLLLEFT:
case PGF_SCROLLRIGHT:
case PGF_SCROLLUP:
case PGF_SCROLLDOWN:
pScroll->iScroll = 20;
break;
}
}
return 0;
This section contains information about the following API elements used with pager controls.
| Notifications |
| NM_RELEASEDCAPTURE (pager) |
| PGN_CALCSIZE |
| PGN_SCROLL |
| Structures |
| NMPGCALCSIZE |
| NMPGSCROLL |
The following window styles are used when creating pager controls.
| PGS_AUTOSCROLL | The pager control will scroll when the user hovers the mouse over one of the scroll buttons. |
| PGS_DRAGNDROP | The contained window can be a drag-and-drop target. The pager control will automatically scroll if an item is dragged from outside the pager over one of the scroll buttons. |
| PGS_HORZ | Creates a pager control that can be scrolled horizontally. This style and the PGS_VERT style are mutually exclusive and cannot be combined. |
| PGS_VERT | Creates a pager control that can be scrolled vertically. This is the default direction if no direction style is specified. This style and the PGS_HORZ style are mutually exclusive and cannot be combined. |
This section contains information about the messages used with pager controls.
PGM_FORWARDMOUSE
wParam = (WPARAM)(BOOL)bForward;
lParam = 0;
Enables or disables mouse forwarding for the pager control. When mouse forwarding is enabled, the pager control forwards WM_MOUSEMOVE messages to the contained window. You can send this message explicitly or use the Pager_ForwardMouse macro.
Version 4.71
PGM_GETBKCOLOR
wParam = 0;
lParam = 0;
Retrieves the current background color for the pager control. You can send this message explicitly or use the Pager_GetBkColor macro.
By default, the pager control will use the system button face color as the background color. This is the same color that can be retrieved by calling GetSysColor with COLOR_BTNFACE.
Version 4.71
PGM_GETBORDER
wParam = 0;
lParam = 0;
Retrieves the current border size for the pager control. You can send this message explicitly or use the Pager_GetBorder macro.
Version 4.71
See also PGM_SETBORDER
PGM_GETBUTTONSIZE
wParam = 0;
lParam = 0;
Retrieves the current button size for the pager control. You can send this message explicitly or use the Pager_GetButtonSize macro.
Version 4.71
See also PGM_SETBUTTONSIZE
PGM_GETBUTTONSTATE
wParam = 0;
lParam = (LPARAM)(int)iButton;
Retrieves the state of the specified button in a pager control. You can send this message explicitly or use the Pager_GetButtonState macro.
| PGF_INVISIBLE | The button is not visible. |
| PGF_NORMAL | The button is in normal state. |
| PGF_GRAYED | The button is in grayed state. |
| PGF_DEPRESSED | The button is in pressed state. |
| PGF_HOT | The button is in hot state. |
| PGB_TOPORLEFT | Indicates the top button in a PGS_VERT pager control or the left button in a PGS_HORZ pager control. |
| PGB_BOTTOMORRIGHT | Indicates the bottom button in a PGS_VERT pager control or the right button in a PGS_HORZ pager control. |
Version 4.71
PGM_GETDROPTARGET
wParam = 0;
lParam = (IDropTarget**)ppDropTarget;
Retrieves a pager control's IDropTarget interface pointer. You can send this message explicitly or use the Pager_GetDropTarget macro.
PGM_GETPOS
wParam = 0;
lParam = 0;
Retrieves the current scroll position of the pager control. You can send this message explicitly or use the Pager_GetPos macro.
Version 4.71
PGM_RECALCSIZE
wParam = 0;
lParam = 0;
Forces the pager control to recalculate the size of the contained window. Sending this message will result in a PGN_CALCSIZE notification being sent. You can send this message explicitly or use the Pager_RecalcSize macro.
Version 4.71
PGM_SETBKCOLOR
wParam = 0;
lParam = (LPARAM)(COLORREF)clrBk;
Sets the current background color for the pager control. You can send this message explicitly or use the Pager_SetBkColor macro.
By default, the pager control will use the system button face color as the background color. This is the same color that can be retrieved by calling GetSysColor with COLOR_BTNFACE.
Version 4.71
PGM_SETBORDER
wParam = 0;
lParam = (LPARAM)(int)iBorder;
Sets the current border size for the pager control. You can send this message explicitly or use the Pager_SetBorder macro.
Version 4.71
PGM_SETBUTTONSIZE
wParam = 0;
lParam = (LPARAM)(int)iButtonSize;
Sets the current button size for the pager control. You can send this message explicitly or use the Pager_SetButtonSize macro.
If the pager control has the PGS_HORZ style, the button size determines the width of the pager buttons. If the pager control has the PGS_VERT style, the button size determines the height of the pager buttons. By default, the pager control sets its button size to three-fourths of the width of the scroll bar.
Version 4.71
See also PGM_GETBUTTONSIZE
PGM_SETCHILD
wParam = 0;
lParam = (LPARAM)(HWND)hwndChild;
Sets the contained window for the pager control. This message will 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. If this is the case, the contained window should be a child of the pager control. You can send this message explicitly or use the Pager_SetChild macro.
Version 4.71
PGM_SETPOS
wParam = 0;
lParam = (LPARAM)(int)iPos;
Sets the current scroll position for the pager control. You can send this message explicitly or use the Pager_SetPos macro.
Version 4.71
This section contains information about the utility macros used with pager controls.
VOID Pager_ForwardMouse(
HWND hwndPager,
BOOL bForward
);
Enables or disables mouse forwarding for the pager control. When mouse forwarding is enabled, the pager control forwards WM_MOUSEMOVE messages to the contained window. You can use this macro or send the PGM_FORWARDMOUSE message explicitly.
Version 4.71
COLORREF Pager_GetBkColor(
HWND hwndPager
);
Retrieves the current background color for the pager control. You can use this macro or send the PGM_GETBKCOLOR message explicitly.
By default, the pager control will use the system button face color as the background color. This is the same color that can be retrieved by calling GetSysColor with COLOR_BTNFACE.
Version 4.71
int Pager_GetBorder(
HWND hwndPager
);
Retrieves the current border size for the pager control. You can use this macro or send the PGM_GETBORDER message explicitly.
Version 4.71
int Pager_GetButtonSize(
HWND hwndPager
);
Retrieves the current button size for the pager control. You can use this macro or send the PGM_GETBUTTONSIZE message explicitly.
Version 4.71
See also Pager_SetButtonSize
DWORD Pager_GetButtonState(
HWND hwndPager;
int iButton
);
Retrieves the state of the specified button in a pager control. You can use this macro or send the PGM_GETBUTTONSTATE message explicitly.
Version 4.71
void Pager_GetDropTarget(
HWND hwndPager,
IDropTarget **ppDropTarget
);
Retrieves a pager control's IDropTarget interface pointer. You can use this macro or send the PGM_GETDROPTARGET message explicitly.
COLORREF Pager_GetPos(
HWND hwndPager
);
Retrieves the current scroll position of the pager control. You can use this macro or send the PGM_GETPOS message explicitly.
Version 4.71
COLORREF Pager_RecalcSize(
HWND hwndPager
);
Forces the pager control to recalculate the size of the contained window. Using this macro will result in a PGN_CALCSIZE notification being sent. You can use this macro or send the PGM_RECALCSIZE message explicitly.
Version 4.71
COLORREF Pager_SetBkColor(
HWND hwndPager,
COLORREF clrBk
);
Sets the current background color for the pager control. You can use this macro or send the PGM_SETBKCOLOR message explicitly.
By default, the pager control will use the system button face color as the background color. This is the same color that can be retrieved by calling GetSysColor with COLOR_BTNFACE.
Version 4.71
INT Pager_SetBorder(
HWND hwndPager,
int iBorder
);
Sets the current border size for the pager control. You can use this macro or send the PGM_SETBORDER message explicitly.
Version 4.71
int Pager_SetButtonSize(
HWND hwndPager,
Int iButtonSize
);
Sets the current button size for the pager control. You can use this macro or send the PGM_SETBUTTONSIZE message explicitly.
If the pager control has the PGS_HORZ style, the button size determines the width of the pager buttons. If the pager control has the PGS_VERT style, the button size determines the height of the pager buttons. By default, the pager control sets its button size to three-fourths of the width of the scroll bar.
Version 4.71
See also Pager_GetButtonSize
COLORREF Pager_SetChild(
HWND hwndPager,
HWND hwndChild
);
Sets the contained window for the pager control. This macro will 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. If this is the case, the contained window should be a child of the pager control. You can use this macro or send the PGM_SETCHILD message explicitly.
Version 4.71
INT Pager_SetPos(
HWND hwndPager,
int iPos
);
Sets the scroll position for the pager control. You can use this macro or send the PGM_SETPOS message explicitly.
Version 4.71
This section contains information about the notification messages sent by pager controls.
NM_RELEASEDCAPTURE
lpnmh = (LPNMHDR) lParam;
Notifies a pager control's parent window that the control has released the mouse capture. NM_RELEASEDCAPTURE is sent in the form of a WM_NOTIFY message.
PGN_CALCSIZE
lpnmcs = (LPNMPGCALCSIZE) lParam;
Notification sent by a pager control to obtain the scrollable dimensions of the contained window. These dimensions are used by the pager control to determine the scrollable size of the contained window. This notification is sent in the form of a WM_NOTIFY message.
Version 4.71
PGN_SCROLL
lpnms = (LPNMPGSCROLL) lParam;
Notification sent by a pager control prior to the contained window being scrolled. This notification is sent in the form of a WM_NOTIFY message.
Version 4.71
This section contains information about the structures used with pager controls.
typedef struct {
NMHDR hdr;
DWORD dwFlag;
int iWidth;
int iHeight;
}NMPGCALCSIZE, *LPNMPGCALCSIZE;
Contains and receives information that the pager control uses to calculate the scrollable area of the contained window. It is used with the PGN_CALCSIZE notification.
| PGF_CALCHEIGHT | The height of the scrollable area is being requested. The height must be placed in the iHeight member before returning from the notification. |
| PGF_CALCWIDTH | The width of the scrollable area is being requested. The width must be placed in the iWidth member before returning from the notification. |
Version 4.71
typedef struct {
NMHDR hdr;
BOOL fwKeys;
RECT rcParent;
int iDir;
int iXpos;
int iYpos;
int iScroll;
}NMPGSCROLL, *LPNMPGSCROLL;
Contains and receives information that the pager control uses when scrolling the contained window. It is used with the PGN_SCROLL notification.
| 0 | None of the modifier keys are down. |
| PGK_SHIFT | The shift key is down. |
| PGK_CONTROL | The control key is down. |
| PGK_MENU | The alt key is down. |
| PGF_SCROLLDOWN | The contained window is being scrolled down. |
| PGF_SCROLLLEFT | The contained window is being scrolled to the left. |
| PGF_SCROLLRIGHT | The contained window is being scrolled to the right. |
| PGF_SCROLLUP | The contained window is being scrolled up. |
Version 4.71
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.