SCROLLINFO
The SCROLLINFO structure contains scroll bar parameters to be set by the SetScrollInfo function (or SBM_SETSCROLLINFO message), or retrieved by the GetScrollInfo function (or SBM_GETSCROLLINFO message).
typedef struct tagSCROLLINFO {
UINT cbSize;
UINT fMask;
int nMin;
int nMax;
UINT nPage;
int nPos;
int nTrackPos;
} SCROLLINFO, *LPSCROLLINFO;
typedef SCROLLINFO CONST *LPCSCROLLINFO;
Members
cbSize
Specifies the size, in bytes, of this structure.
fMask
Specifies the scroll bar parameters to set or retrieve. This member can be a combination of the following values: Value Meaning
SIF_ALL Combination of SIF_PAGE, SIF_POS, SIF_RANGE, and SIF_TRACKPOS.
SIF_DISABLENOSCROLL This value is used only when setting a scroll bar's parameters. If the scroll bar's new parameters make the scroll bar unnecessary, disable the scroll bar instead of removing it.
SIF_PAGE The nPage member contains the page size for a proportional scroll bar.
SIF_POS The nPos member contains the scroll box position, which is not updated while the user drags the scroll box.
SIF_RANGE The nMin and nMax members contain the minimum and maximum values for the scrolling range.
SIF_TRACKPOS The nTrackPos member contains the current position of the scroll box while the user is dragging it.
nMin
Specifies the minimum scrolling position.
nMax
Specifies the maximum scrolling position.
nPage
Specifies the page size. A scroll bar uses this value to determine the appropriate size of the proportional scroll box.
nPos
Specifies the position of the scroll box.
nTrackPos
Specifies the immediate position of a scroll box that the user is dragging. An application can retrieve this value while processing the SB_THUMBTRACK request code. An application cannot set the immediate scroll position; the SetScrollInfo function ignores this member.
Requirements
Windows NT/2000/XP: Included in Windows NT 3.51 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winuser.h; include Windows.h.
See Also
Scroll Bars Overview, Scroll Bar Structures, SBM_GETSCROLLINFO, SBM_SETSCROLLINFO, GetScrollInfo, SetScrollInfo
GetScrollInfo
The GetScrollInfo function retrieves the parameters of a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (thumb).
BOOL GetScrollInfo(
HWND hwnd, // handle to window
int fnBar, // scroll bar type
LPSCROLLINFO lpsi // scroll bar parameters
);
Parameters
hwnd
[in] Handle to a scroll bar control or a window with a standard scroll bar, depending on the value of the fnBar parameter.
fnBar
[in] Specifies the type of scroll bar for which to retrieve parameters. This parameter can be one of the following values. Value Meaning
SB_CTL Retrieves the parameters for a scroll bar control. The hwnd parameter must be the handle to the scroll bar control.
SB_HORZ Retrieves the parameters for the window's standard horizontal scroll bar.
SB_VERT Retrieves the parameters for the window's standard vertical scroll bar.
lpsi
[in/out] Pointer to a SCROLLINFO structure. Before calling GetScrollInfo, set the cbSize member of the structure to sizeof(SCROLLINFO), and set the fMask member to specify the scroll bar parameters to retrieve. Before returning, the function copies the specified parameters to the appropriate members of the structure.
The fMask member can be one or more of the following values. Value Meaning
SIF_PAGE Copies the scroll page to the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS Copies the scroll position to the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE Copies the scroll range to the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.
SIF_TRACKPOS Copies the current scroll box tracking position to the nTrackPos member of the SCROLLINFO structure pointed to by lpsi.
Return Values
If the function retrieved any values, the return value is nonzero.
If the function does not retrieve any values, the return value is zero. To get extended error information, call GetLastError.
Remarks
The GetScrollInfo function enables applications to use 32-bit scroll positions. Although the messages that indicate scroll-bar position, WM_HSCROLL and WM_VSCROLL, provide only 16 bits of position data, the functions SetScrollInfo and GetScrollInfo provide 32 bits of scroll-bar position data. Thus, an application can call GetScrollInfo while processing either the WM_HSCROLL or WM_VSCROLL messages to obtain 32-bit scroll-bar position data.
To get the 32-bit position of the scroll box (thumb) during a SB_THUMBTRACK request code in a WM_HSCROLL or WM_VSCROLL message, call GetScrollInfo with the SIF_TRACKPOS value in the fMask member of the SCROLLINFO structure. The function returns the tracking position of the scroll box in the nTrackPos member of the SCROLLINFO structure. This allows you to get the position of the scroll box as the user moves it. The following sample code illustrates the technique.
SCROLLINFO si;
case WM_HSCROLL:
switch(LOWORD(wparam)) {
case SB_THUMBTRACK:
// Initialize SCROLLINFO structure
ZeroMemory(&si, sizeof(SCROLLINFO));
si.cbSize = sizeof(SCROLLINFO);
si.fMask = SIF_TRACKPOS;
// Call GetScrollInfo to get current tracking
// position in si.nTrackPos
if (!GetScrollInfo(hwnd, SB_HORZ, &si) )
return 1; // GetScrollInfo failed
break;
.
.
.
}
Requirements
Windows NT/2000/XP: Included in Windows NT 3.51 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winuser.h; include Windows.h.
Library: Use User32.lib.
See Also
Scroll Bars Overview, Scroll Bar Functions, SCROLLINFO, SetScrollInfo, WM_HSCROLL, WM_VSCROLL
SetScrollInfo
The SetScrollInfo function sets the parameters of a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (thumb). The function also redraws the scroll bar, if requested.
int SetScrollInfo(
HWND hwnd, // handle to window
int fnBar, // scroll bar type
LPCSCROLLINFO lpsi, // scroll parameters
BOOL fRedraw // redraw flag
);
Parameters
hwnd
[in] Handle to a scroll bar control or a window with a standard scroll bar, depending on the value of the fnBar parameter.
fnBar
[in] Specifies the type of scroll bar for which to set parameters. This parameter can be one of the following values. Value Meaning
SB_CTL Sets the parameters of a scroll bar control. The hwnd parameter must be the handle to the scroll bar control.
SB_HORZ Sets the parameters of the window's standard horizontal scroll bar.
SB_VERT Sets the parameters of the window's standard vertical scroll bar.
lpsi
[in] Pointer to a SCROLLINFO structure. Before calling SetScrollInfo, set the cbSize member of the structure to sizeof(SCROLLINFO), set the fMask member to indicate the parameters to set, and specify the new parameter values in the appropriate members.
The fMask member can be one or more of the following values. Value Meaning
SIF_DISABLENOSCROLL Disables the scroll bar instead of removing it, if the scroll bar's new parameters make the scroll bar unnecessary.
SIF_PAGE Sets the scroll page to the value specified in the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS Sets the scroll position to the value specified in the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE Sets the scroll range to the value specified in the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.
fRedraw
[in] Specifies whether the scroll bar is redrawn to reflect the changes to the scroll bar. If this parameter is TRUE, the scroll bar is redrawn, otherwise, it is not redrawn.
Return Values
The return value is the current position of the scroll box.
Remarks
The SetScrollInfo function performs range checking on the values specified by the nPage and nPos members of the SCROLLINFO structure. The nPage member must specify a value from 0 to nMax - nMin +1. The nPos member must specify a value between nMin and nMax - max(nPage – 1, 0). If either value is beyond its range, the function sets it to a value that is just within the range.
Example Code
For an example, see Example of Scrolling Text.
Requirements
Windows NT/2000/XP: Included in Windows NT 3.51 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winuser.h; include Windows.h.
Library: Use User32.lib.
See Also
Scroll Bars Overview, Scroll Bar Functions, GetScrollInfo, SCROLLINFO
ScrollWindow
The ScrollWindow function scrolls the contents of the specified window's client area.
Note The ScrollWindow function is provided for backward compatibility. New applications should use the ScrollWindowEx function.
BOOL ScrollWindow(
HWND hWnd, // handle to window
int XAmount, // horizontal scrolling
int YAmount, // vertical scrolling
CONST RECT *lpRect, // client area
CONST RECT *lpClipRect // clipping rectangle
);
Parameters
hWnd
[in] Handle to the window where the client area is to be scrolled.
XAmount
[in] Specifies the amount, in device units, of horizontal scrolling. If the window being scrolled has the CS_OWNDC or CS_CLASSDC style, then this parameter uses logical units rather than device units. This parameter must be a negative value to scroll the content of the window to the left.
YAmount
[in] Specifies the amount, in device units, of vertical scrolling. If the window being scrolled has the CS_OWNDC or CS_CLASSDC style, then this parameter uses logical units rather than device units. This parameter must be a negative value to scroll the content of the window up.
lpRect
[in] Pointer to the RECT structure specifying the portion of the client area to be scrolled. If this parameter is NULL, the entire client area is scrolled.
lpClipRect
[in] Pointer to the RECT structure containing the coordinates of the clipping rectangle. Only device bits within the clipping rectangle are affected. Bits scrolled from the outside of the rectangle to the inside are painted; bits scrolled from the inside of the rectangle to the outside are not painted.
Return Values
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If the caret is in the window being scrolled, ScrollWindow automatically hides the caret to prevent it from being erased and then restores the caret after the scrolling is finished. The caret position is adjusted accordingly.
The area uncovered by ScrollWindow is not repainted, but it is combined into the window's update region. The application eventually receives a WM_PAINT message notifying it that the region must be repainted. To repaint the uncovered area at the same time the scrolling is in action, call the UpdateWindow function immediately after calling ScrollWindow.
If the lpRect parameter is NULL, the positions of any child windows in the window are offset by the amount specified by the XAmount and YAmount parameters; invalid (unpainted) areas in the window are also offset. ScrollWindow is faster when lpRect is NULL.
If lpRect is not NULL, the positions of child windows are not changed and invalid areas in the window are not offset. To prevent updating problems when lpRect is not NULL, call UpdateWindow to repaint the window before calling ScrollWindow.
Example Code
For an example, see Example of Scrolling Text.
Requirements
Windows NT/2000/XP: Included in Windows NT 3.1 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winuser.h; include Windows.h.
Library: Use User32.lib.
See Also
Scroll Bars Overview, Scroll Bar Functions, RECT, ScrollDC, ScrollWindowEx, UpdateWindow
UpdateWindow
The UpdateWindow function updates the client area of the specified window by sending a WM_PAINT message to the window if the window's update region is not empty. The function sends a WM_PAINT message directly to the window procedure of the specified window, bypassing the application queue. If the update region is empty, no message is sent.
BOOL UpdateWindow(
HWND hWnd // handle to window
);
Parameters
hWnd
[in] Handle to the window to be updated.
Return Values
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero.
Windows NT/2000/XP: To get extended error information, call GetLastError.
Example Code
For an example, see Drawing in the Client Area.
Requirements
Windows NT/2000/XP: Included in Windows NT 3.1 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winuser.h; include Windows.h.
Library: Use User32.lib.
See Also
Painting and Drawing Overview, Painting and Drawing Functions, ExcludeUpdateRgn, GetUpdateRect, GetUpdateRgn, InvalidateRect, InvalidateRgn, WM_PAINT