Pager Controls

Pager Controls


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.

arrowy.gifAbout Pager Controls

arrowy.gifUsing Pager Controls

arrowy.gifPager Control Reference

About Pager Controls

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.

Using Pager Controls

This section describes how to implement the pager control in your application.

Initializing the Pager Control

To use the pager control, you must call InitCommonControlsEx with the ICC_PAGESCROLLER_CLASSES flag set in the dwICC member of the INITCOMMONCONTROLSEX structure.

Creating the Pager Control

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.

Processing Pager Control Notifications

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;

Pager Control Reference

This section contains information about the following API elements used with pager controls.

Pager Control Styles

Messages
PGM_FORWARDMOUSE
PGM_GETBKCOLOR
PGM_GETBORDER
PGM_GETBUTTONSIZE
PGM_GETBUTTONSTATE
PGM_GETDROPTARGET
PGM_GETPOS
PGM_RECALCSIZE
PGM_SETBKCOLOR
PGM_SETBORDER
PGM_SETBUTTONSIZE
PGM_SETCHILD
PGM_SETPOS

Utility Macros
Pager_ForwardMouse
Pager_GetBkColor
Pager_GetBorder
Pager_GetButtonSize
Pager_GetButtonState
Pager_GetDropTarget
Pager_GetPos
Pager_RecalcSize
Pager_SetBkColor
Pager_SetBorder
Pager_SetButtonSize
Pager_SetChild
Pager_SetPos

Notifications
NM_RELEASEDCAPTURE (pager)
PGN_CALCSIZE
PGN_SCROLL

Structures
NMPGCALCSIZE
NMPGSCROLL

Pager Control Styles

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.

Pager Control Messages

This section contains information about the messages used with pager controls.

PGM_FORWARDMOUSE
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.

bForward
BOOL value that determines if mouse forwarding is enabled or disabled. If this value is nonzero, mouse forwarding is enabled. If this value is zero, mouse forwarding is disabled.

Version 4.71

PGM_GETBKCOLOR
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
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
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
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.

iButton
Indicates which button to retrieve the state for. This can be one of the following values:
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
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.

ppDropTarget
Address of an IDropTarget pointer that receives the interface pointer. It is the caller's responsibility to call Release on this pointer when it is no longer needed.
PGM_GETPOS
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
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
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.

clrBk
COLORREF value that contains the new background color of the pager control.

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

iBorder
INT value that contains the new size of the border, in pixels.

Version 4.71

PGM_SETBUTTONSIZE
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.

iButtonSize
INT value that contains the new button size, in pixels.

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

hwndChild
Handle to the window to be contained.

Version 4.71

PGM_SETPOS
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.

iPos
INT value that contains the new scroll position, in pixels.

Version 4.71

Pager Control Utility Macros

This section contains information about the utility macros used with pager controls.

Pager_ForwardMouse
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.

hwndPager
Handle to the pager control.
bForward
BOOL value that determines if mouse forwarding is enabled or disabled. If this value is nonzero, mouse forwarding is enabled. If this value is zero, mouse forwarding is disabled.

Version 4.71

Pager_GetBkColor
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.

hwndPager
Handle to the pager control.

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

Pager_GetBorder
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.

hwndPager
Handle to the pager control.

Version 4.71

Pager_GetButtonSize
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.

hwndPager
Handle to the pager control.

Version 4.71

See also Pager_SetButtonSize

Pager_GetButtonState
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.

hwndPager
Handle to the pager control.
iButton
Indicates which button to retrieve the state for. See the description for iButton in PGM_GETBUTTONSTATE for a list of possible values.

Version 4.71

Pager_GetDropTarget
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.

hwndPager
Handle to the pager control.
ppDropTarget
Address of an IDropTarget pointer that receives the interface pointer. It is the caller's responsibility to call Release on this pointer when it is no longer needed.
Pager_GetPos
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.

hwndPager
Handle to the pager control.

Version 4.71

Pager_RecalcSize
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.

hwndPager
Handle to the pager control.

Version 4.71

Pager_SetBkColor
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.

hwndPager
Handle to the pager control.
clrBk
COLORREF value that contains the new background color of the pager control.

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

Pager_SetBorder
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.

hwndPager
Handle to the pager control.
iBorder
INT value that contains the new size of the border, in pixels.

Version 4.71

Pager_SetButtonSize
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.

hwndPager
Handle to the pager control.
iButtonSize
INT value that contains the new button size, in pixels.

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

Pager_SetChild
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.

hwndPager
Handle to the pager control.
hwndChild
Handle to the window to be contained.

Version 4.71

Pager_SetPos
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.

hwndPager
Handle to the pager control.
iPos
INT value that contains the new scroll position, in pixels.

Version 4.71

Pager Control Notifications

This section contains information about the notification messages sent by pager controls.

NM_RELEASEDCAPTURE (pager)
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.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.
PGN_CALCSIZE
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.

lpnmcs
Address of an NMPGCALCSIZE structure that contains and receives information about the notification. The dwFlag member of this structure indicates which dimension is being calculated. Depending on the value of dwFlags, you should place the desired dimension in the iWidth or iHeight member of this structure.

Version 4.71

PGN_SCROLL
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.

lpnms
Address of an NMPGSCROLL structure that contains and receives information about the notification. The iDir member of this structure indicates the direction of the scroll. The iXpos and iYpos members contain the horizontal and vertical position of the contained window prior to the scroll. The iScroll member contains the default scroll delta amount. You can modify this member to a different scroll amount if desired.

Version 4.71

Pager Control Structures

This section contains information about the structures used with pager controls.

NMPGCALCSIZE
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.

hdr
NMHDR structure that contains information about the notification message.
dwFlag
Value that indicates which dimension is being requested. This will be one of the following values:
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.
iWidth
Receives the desired width of the scrollable area, in pixels.
iHeight
Receives the desired height of the scrollable area, in pixels.

Version 4.71

NMPGSCROLL
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.

hdr
NMHDR structure that contains information about the notification message.
fwKeys
Specifies which of the modifier keys are down when the scroll occurs. This can be one or more of the following values:
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.
rcParent
Contains the client rectangle of the pager control.
iDir
Value that indicates in which direction the scroll is occurring. This will be one of the following values:
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.
iXpos
Contains the horizontal scroll position of the contained window, in pixels, before the scroll action.
iYpos
Contains the vertical scroll position of the contained window, in pixels, before the scroll action.
iScroll
On entry, contains the default scroll delta in pixels. This member can be modified to contain a different scroll delta amount if desired. This value is always positive, regardless of the scroll direction.

Version 4.71

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.