WinGetScreenPS

This method returns a presentation space that can be used for drawing anywhere on the screen.

Syntax

HPS WinGetScreenPS(hwndDeskTop);

Parameters

hwndDeskTop (HWND) - input: Desktop-window handle.; HWND_DESKTOP: The desktop-window handle.; Other: Specified desktop-window handle.

Returns

hpsScreenPS (HPS) - returns: Presentation-space handle.; A micro presentation space that can be used for drawing over the entire desktop window (the whole screen).; NULLHANDLE: hwndDeskTop is not HWND_DESKTOP or a desktop window handle obtained from the WinQueryDesktopWindow function.; Other: Presentation space handle.

Errors

Possible returns from WinGetLastError

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

Remarks

Take great care when using this method. The returned presentation space is not clipped to any of the other windows present on the screen. Thus it is possible to draw in regions belonging to windows of other threads and processes.

The WinLockWindowUpdate function should be used to avoid simultaneous updates to the same part of the screen. This does not cause the presentation space returned by this function to become clipped in any way. Care of the appearance of windows of other threads is still the responsibility of the user of the screen presentation space.

When the application finishes using the screen presentation space, it should be destroyed using the WinReleasePS call.

Example Code

Declaration:

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

HWND     hwndDeskTop;    /*  Desktop-window handle. */
HPS      hpsScreenPS;    /*  Presentation-space handle. */

hpsScreenPS = WinGetScreenPS(hwndDeskTop);

This example processes an application-defined message (IDM_FILL). It calls WinGetScreenPS to get a presentation space for the entire desktop window, gets the dimensions of the current window, fills the window, and calls WinReleasePS to release the presentation space.

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

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

case IDM_FILL:
    /* get presentation space for the entire desktop */
    hps = WinGetScreenPS(HWND_DESKTOP);

    WinQueryWindowRect(hwnd, &rcl);    /* get window dimensions */

    WinFillRect(hps, &rcl, CLR_WHITE); /* clear entire window   */

    WinReleasePS(hps);             /* release the presentation space   *
    return 0L;

Related Functions