GpiSetDrawingMode
This function sets the drawing mode to control the handling of subsequent individual drawing primitive and attribute calls.
Syntax
GpiSetDrawingMode(hps, lMode)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- lMode (LONG) - input
- Mode to be used for subsequent drawing calls.
- This parameter can contain a combination of the following values:
- DM_DRAW
- Draw, unless in an unchained segment
- DM_RETAIN
- Retain, if within a segment
- DM_DRAWANDRETAIN
- Draw-and-retain, combination of above.
Return Code
- rc (BOOL) - returns
- Success indicator.
- TRUE
- Successful completion
- FALSE
- Error occurred.
Errors
Possible returns from WinGetLastError
- PMERR_INV_HPS (0x207F)
An invalid presentation-space handle was specified.
- PMERR_PS_BUSY (0x20F4)
- An attempt was made to access the presentation space from more than one thread simultaneously.
- PMERR_INV_MICROPS_FUNCTION (0x20A1)
- An attempt was made to issue a function that is invalid in a micro presentation space.
- 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.
- PMERR_INV_IN_PATH (0x208B)
- An attempt was made to issue a function invalid inside a path bracket.
- PMERR_INV_IN_ELEMENT (0x2089)
- An attempt was made to issue a function invalid inside an element bracket.
- PMERR_INV_IN_SEG (0x208D)
- An attempt was made to issue a function invalid inside a segment bracket.
- PMERR_INV_DRAWING_MODE (0x2065)
- An invalid mode parameter was specified with GpiSetDrawControl not draw-and-retain or draw.
Remarks
The drawing mode affects the handling of subsequent individual drawing primitive and attribute calls, and the GpiPutData, GpiElement, and GpiPlayMetaFile functions.
Primitives and attributes can be drawn immediately, retained, or both, in the current segment.
Note: Any primitive and attribute setting calls that occur outside a segment (that is, outside a GpiOpenSegment - GpiCloseSegment bracket) are always treated as nonretained. Conversely, any segments that are not chained are always retained. This table summarizes how the actual drawing mode is arrived at:
| Parameter | Context | ||
|---|---|---|---|
| Chained Segment | Unchained Segment | Outside Segment | |
| DM_DRAWANDRETAIN | draw-and-retain | retain | draw |
| DM_RETAIN | retain | retain | draw |
| DM_DRAW | draw | retain | draw |
The actual drawing mode (referred to when describing other Gpi calls) therefore depends upon the mode as set by GpiSetDrawingMode, together with the context, as in the table. It is this actual drawing mode that determines whether a drawing call is retained (retain or draw-and-retain), and whether it is drawn immediately (draw or draw-and-retain).
It is an error to try to set the drawing mode within a segment bracket, and also outside a segment bracket, if in one of the following:
Area bracket
Element bracket
Path bracket.
The default drawing mode is DM_DRAW.
Example Code
#define INCL_GPICONTROL /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> HPS hps; /* Presentation-space handle. */ LONG lMode; /* Mode to be used for subsequent drawing calls. */ BOOL rc; /* Success indicator. */ rc = GpiSetDrawingMode(hps, lMode);
This example calls GpiSetDrawingMode to set the drawing mode to DRAW.
#define INCL_GPICONTROL /* GPI control Functions */ #include <os2.h> BOOL fSuccess; /* success indicator */ HPS hps; /* Presentation-space handle */ fSuccess = GpiSetDrawingMode(hps, DM_DRAW);