GreSaveDC

GreSaveDC saves the device context's state on a stack and returns an identifier to allow for its subsequent restoration.

This function is supported by the graphics engine.

Syntax

GreSaveDC(hdc, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreSaveDC.

Return Code

rc (LONG) - returns

Return codes.

This function returns the identifier for the saved DC state (idDC), or it returns GPI_ERROR if an error occurs.

Possible Errors Detected: When an error is detected, the graphics engine calls WinSetErrorInfo to post the condition. Reasons for failure of this function include:

• PMERR_BASE_ERROR
• PMERR_DEV_FUNC_NOT_INSTALLED
• PMERR_EXCEEDS_MAX_SEG_LENGTH
• PMERR_HDC_BUSY
• PMERR_INSUFFICIENT_MEMORY
• PMERR_INV_CODEPAGE
• PMERR_INV_COORDINATE
• PMERR_INV_DC_TYPE
• PMERR_INV_HDC
• PMERR_INV_HRGN
• PMERR_INV_IN_AREA
• PMERR_INV_IN_PATH
• PMERR_INV_RECT
• PMERR_INV_REGION_CONTROL

Refer to the "Error Explanations" section of the Presentation Manager Programming Reference for further explanation.

Remarks

The following information is saved:

• Current position
• Current attributes
• Current transforms, viewing limits, and clip path
• Any reference to a selected clip window
• Any loaded logical color table
• References to any loaded logical fonts
• References to the regions created on the associated DC

The following are not saved:

• Visible region
• Process controls

Any resources such as clip region and logical fonts, which are referenced in a saved DC, should not be deleted. The ID of a saved DC is only unique within the DC for which it is issued. Other DCs can have saved states with the same ID. The returned identifier can be used for a subsequent GreRestoreDC. This identifier represents the level of the saved DC on the save/restore stack. The first DC saved is identified by a value of 1, the second by 2, and so on.

Sample Code

#define INCL_GRE_DCS
#include <os2.h>

HDC      hdc;        /*  Device context handle. */
PVOID    pInstance;  /*  Pointer to instance data. */
ULONG    lFunction;  /*  High-order WORD=flags; low-order WORD=NGreSaveDC. */
LONG     rc;         /*  Return codes. */

rc = GreSaveDC(hdc, pInstance, lFunction);