WinGetPS

This method gets a cache presentation space.

Syntax

WinGetPS(hwnd)

Parameter

hwnd (HWND) - input

Handle of window for which the presentation space is required.

HWND_DESKTOP - The desktop-window handle; a presentation space for the whole of the desktop window is returned

Other - Handle of window for which the presentation space is required.

Returns

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

Errors

Possible returns from WinGetLastError

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

Remarks

The presentation space created 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.

The initial state of the presentation space is the same as that of a presentation space created using GpiCreatePS. The color table is in default color index mode. The visible region associated with hps depends upon the window and class styles of hwnd:

Style Flags
Style	Description
Visible region of presentation space
WS_CLIPCHILDREN	All child windows of the window are excluded.
WS_CLIPSIBLINGS	All the sibling windows of hwnd are excluded.
CS_PARENTCLIP	Is the same as that of the parent window of the window.

The presentation space origin is established normally, that is, relative to the lower left of the window itself, not its parent.

This style optimizes the use of the presentation space cache by minimizing the calculation of the visible region for child windows.

Any presentation space created by WinGetPS must be released by calling WinReleasePS. This should be done before the application terminates.

Note: This call requires the presence of a message queue and should not be made until after the application's message queue has been created.

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. */
HPS     hps;   /*  Presentation-space handle that can be used for drawing in the window. */

hps = WinGetPS(hwnd);

This example processes an application-defined message (IDM_FILL). It calls WinGetPS to get a presentation space to the entire window. It 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:
    hps = WinGetPS(hwnd);       /* get presentation space for   */
                                /* the entire window */

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

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

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

Related Functions