WinScrollWindow

This function scrolls the contents of a window rectangle.

Syntax

WinScrollWindow(hwnd, lDx, lDy, prclScroll, prclClip, hrgnUpdateRgn, prclUpdate, flOptions)

Parameters

hwnd (HWND) - Input

Window handle.

lDx (LONG) - Input

Amount of horizontal scroll to the right (in device units).

lDy (LONG) - Input

Amount of vertical scroll upward (in device units).

prclScroll (PRECTL) - Input

Scroll rectangle.

If this is NULL, the entire window is scrolled.

Note: The value of each field in this structure must be in the range -32 768 through 32 767. The data type WRECT may also be used, if supported by the language.

prclClip (PRECTL) - Input

Clip rectangle.

If not NULL, this defines a clip rectangle that clips the destination of the scroll.

hrgnUpdateRgn (HRGN) - Input

Update region.

If not NULLHANDLE, this contains the region uncovered by the scroll when returned.

prclUpdate (PRECTL) - In/Out

Update rectangle.

If not NULL, this contains the bounding rectangle of the invalid bits uncovered by the scroll when returned.

flOptions (ULONG) - Input

Scroll options.

SW_SCROLLCHILDREN: Unless this is set, child windows are not scrolled. If this is set, and prclScroll is NULL, all the child windows are scrolled by lDx and lDy units. If prclScroll is not NULL, only those child windows that intersect prclScroll are scrolled.
SW_INVALIDATERGN: The invalid region created as a result of the scroll is added to the update regions of those windows affected. This may result in sending WM_PAINT messages to CS_SYNCPAINT windows before the call returns.

Returns

lComplexity (LONG) - returns

Complexity of resulting region/error indicator.

RGN_NULL: NULL rectangle invalid
RGN_RECT: Simple rectangle invalid
RGN_COMPLEX: Complex rectangle invalid
RGN_ERROR: Error

Remarks

This function scrolls the contents of a rectangle defined by prclScroll in the window hwnd, by lDx units horizontally and lDy units vertically. All coordinates must be in device units. Clipping takes place on the final image of the scrolling. Even if the scroll rectangle lies outside the clip rectangle, these bits are scrolled, if their destination lies within the intersection of the clip rectangle and the destination rectangle. This function returns an RGN_* value, indicating the type of invalid region created by the scroll as returned by GpiCombineRegion. RGN_ERROR is returned if hwnd is invalid.

Note: If hwnd has style WS_CLIPCHILDREN, portions of any child window within the scroll area are scrolled. In this instance, this function must be called with flOptions SW_SCROLLCHILDREN.

This is the only function that can be used by a thread to move bits within its own window, because of the critical section nature of window update regions. Scrolling is fastest without SW_SCROLLCHILDREN and SW_INVALIDATERGN. When scrolling needs to be repeated quickly, do not include the SW_INVALIDATERGN flag and repaint the invalid area if the invalid region is rectangular, otherwise invalidate and update. If the scrolling is infrequent, include the SW_INVALIDATERGN flag. This function invalidates and updates synchronous-paint windows automatically before returning. The cursor and the track rectangle are scrolled when they intersect with the scrolled region. Any part of the window's initial update region that intersects the scrolled region is also offset.

Errors

Possible returns from WinGetLastError:

PMERR_INVALID_HWND (0x1001): An invalid window handle was specified.
PMERR_INVALID_FLAG (0x1019): An invalid bit was set for a parameter. Use constants defined by PM for options, and do not set any reserved bits.
PMERR_HRGN_BUSY (0x2034): An internal region busy error was detected. The region was locked by one thread during an attempt to access it from another thread.

Example Code

#define INCL_WINWINDOWMGR /* Or use INCL_WIN, INCL_PM, Also in COMMON section */
#include <os2.h>

HWND     hwnd;           /*  Window handle. */
LONG     lDx;            /*  Amount of horizontal scroll to the right (in device units). */
LONG     lDy;            /*  Amount of vertical scroll upward (in device units). */
PRECTL   prclScroll;     /*  Scroll rectangle. */
PRECTL   prclClip;       /*  Clip rectangle. */
HRGN     hrgnUpdateRgn;  /*  Update region. */
PRECTL   prclUpdate;     /*  Update rectangle. */
ULONG    flOptions;      /*  Scroll options. */
LONG     lComplexity;    /*  Complexity of resulting region/error indicator. */

lComplexity = WinScrollWindow(hwnd, lDx, lDy, prclScroll, prclClip, hrgnUpdateRgn, prclUpdate, flOptions);

This example shows a very small part of the processing that must be done for a WM_VSCROLL message, which will be sent when a vertical scroll bar has a significant event to notify its owner.

#define INCL_WINSCROLLBARS
#define INCL_WINWINDOWMGR
#include <OS2.H>
#define COUNT 10

HWND   hwndClient;
MPARAM mp2;
ULONG  msg;

switch(msg)
{
case WM_VSCROLL:
    switch (SHORT2FROMMP(mp2))
    {
        case SB_LINEUP:     /*  Sent if the operator      */
                            /*  clicks on the up arrow    */
                            /*  of the scroll bar, or     */
                            /*  presses the VK_UP key. */
            WinScrollWindow(hwndClient,
                            0,
                            (LONG)20,  /* vertical scroll */
                            (PRECTL)NULL,
                            (PRECTL)NULL,
                            (HRGN)NULLHANDLE,
                            (PRECTL)NULL,
                            0);
            break;
    }
break;
}

Related Functions