WinGetClipPS

This method obtains a clipped cache presentation space.

Syntax

WinGetClipPS(hwnd, hwndClipWindow, ulClipflags)

Parameter

hwnd (HWND)

Handle of window for which the presentation space is required.

hwndClipWindow (HWND)

Handle of window for clipping.

HWND_BOTTOM - Clip the last window in the sibling chain and continue clipping until the next window is hwnd or NULLHANDLE.

HWND_TOP - Clip the first window in the sibling chain and continue clipping until the next window is hwnd or NULLHANDLE.

NULLHANDLE - Clip all siblings to the window hwnd.

ulClipflags (ULONG)

Clipping control flags.

PSF_CLIPSIBLINGS - Clip out all siblings of hwnd.

PSF_CLIPCHILDREN - Clip out all children of hwnd.

PSF_CLIPUPWARDS - Taking hwndClipWindow as a reference window, clip out all sibling windows before hwndClipWindow. This value may not be used with PSF_CLIPDOWNWARDS.

PSF_CLIPDOWNWARDS - Taking hwndClipWindow as a reference window, clip out all sibling windows after hwndClipWindow. This value may not be used with PSF_CLIPUPWARDS.

PSF_LOCKWINDOWUPDATE - Calculate a presentation space that keeps a visible region even though output may be locked by the WinLockWindowUpdate function.

PSF_PARENTCLIP - Calculate a presentation space that uses the visible region of the parent of hwnd but with an origin calculated for hwnd.

Returns

hps (HPS): Presentation-space handle that can be used for drawing.

Errors

Possible returns from WinGetLastError

PMERR_INVALID_HWND (0x1001): An invalid window handle was specified.

Remarks

The presentation space obtained by this method is a cache "micro-presentation space" present in the system. This can be used for simple drawing operations that do not depend on long-term data being stored in the presentation space.

When the application finishes using the clipped cache presentation space, it should destroyed it using the WinReleasePS function.

Example Code

Declaration:

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

HWND     hwnd;            /*  Handle of window for which the presentation space is required. */
HWND     hwndClipWindow;  /*  Handle of window for clipping. */
ULONG    ulClipflags;     /*  Clipping control flags. */
HPS      hps;             /*  Presentation-space handle that can be used for drawing. */

hps = WinGetClipPS(hwnd, hwndClipWindow, ulClipflags);

This example responds to an application defined message (IDM_FILL) and uses WinGetClipPS to obtain and associate a cached presentation space with a window, where the PS is clipped to the children of the window.

#define INCL_WINWINDOWMGR       /* Window Manager Functions     */
#include <os2.h>

HWND    hwnd;           /* PS window                            */
HWND    hwndClip;       /* clipping window                      */
RECTL  rcl;             /* update region                        */
HPS    hps;             /* presentation-space handle            */

case IDM_FILL:
     hps = WinGetClipPS(hwnd,   /* handle of the PS window */
         hwndClip,               /* handle of clipping window */
         PSF_CLIPCHILDREN);      /* clipping flags */
     WinFillRect(hps, &rcl, CLR_WHITE);
     WinReleasePS(hps);

Related Functions