WinRealizePalette

This function indicates that drawing is about to take place after a palette has been selected.

Syntax

WinRealizePalette(hwnd, hps, pcclr);

Parameters

hwnd (HWND) - input: Window handle where drawing is taking place.

hps (HPS) - input: Presentation-space handle.

pcclr (PULONG) - output: Number of physical palette entries changed.; A value of zero indicates that the palette was successfully realized without changing any entries in the display hardware physical table. A non-zero value gives the number of hardware table entries that were changed and indicates that a WM_REALIZEPALETTE message has been posted to all other applications.

Returns

lChanged (LONG) - returns: Number of colors remapped.; PAL_ERROR: Error occurred.; Otherwise: Number of colors that are remapped. This includes both animating and non-animating indexes that have matches in the physical palette. This information can be used to determine whether the window needs repainting.
Note: This information may already be out of date if there are other palette-using applications running.

Errors

Possible returns from WinGetLastError

PMERR_NO_PALETTE_SELECTED (0x2110): An attempt to realize a palette failed because no palette was previously selected into the Presentation Space.
PMERR_INVALID_HWND (0x1001): An invalid window handle was specified.
PMERR_INV_HDC (0x207C): An invalid device-context handle or (micro presentation space) presentation-space handle was specified.
PMERR_HDC_BUSY (0x2033): An internal device context busy error was detected. The device context was locked by one thread during an attempt to access it from another thread.
PMERR_INV_IN_AREA (0x2085): An attempt was made to issue a function invalid inside an area bracket. This can be detected while the actual drawing mode is **draw** or **draw-and-retain** or during segment drawing or correlation functions.

Remarks

This function is typically used after GpiSelectPalette or in response to a WM_REALIZEPALETTE message. It causes the system to ensure that the palette is appropriately realized for all drawing operations.

When the window has the input focus, the palette will be realized absolutely. Otherwise, the realization is on a best-can-do basis. If the palette is larger than the currently associated device can support, as many entries as possible are realized, starting from the lowest index.

If the presentation space is currently associated with a device context of type OD_MEMORY (see DevOpenDC), then this function performs no function other than returning without error.

This function must not be called while processing a WM_SETFOCUS message, because a window's activation state is not known until processing of this message is complete.

Note that the palette cannot be physically changed on all devices. The effect of this call is therefore device dependent.

Example Code

Declaration:

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

HWND      hwnd;      /*  Window handle where drawing is taking place. */
HPS       hps;       /*  Presentation-space handle. */
PULONG    pcclr;     /*  Number of physical palette entries changed. */
LONG      lChanged;  /*  Number of colors remapped. */

lChanged = WinRealizePalette(hwnd, hps, pcclr);

In this example, the WinRealizePalette call is issued in response to a WM_REALIZEPALETTE. This ensures that the palette is appropriately realized for all drawing operations.

#define INCL_WIN
#include <OS2.H>
HWND hwnd;
ULONG cclr;
USHORT msg;
HPS hps;

switch(msg)
{
 case WM_REALIZEPALETTE:

 WinRealizePalette(hwnd,hps,&cclr);
}

Related Functions

Related Messages