GpiSetDrawControl

This function sets options for subsequent drawing operations.

Syntax

GpiSetDrawControl(hpsHps, lControl, lValue)

Parameters

hps (HPS) - input

Handle to presentation space

lControl (LONG) - input

Attribute of the Gpi subsystem. Drawing control.

Note: : Controls identified by an asterisk (*) are the only ones relevant to a micro-presentation space. Any other control settings are ignored for a micro-presentation space.

DCTL_ERASE: Erase before draw. Perform an implicit GpiErase operation before GpiDrawChain, GpiDrawFrom, or GpiDrawSegment. The output display area of the Device Context associated with the specified presentation space is cleared before drawing.

DCTL_DISPLAY (*): Enable drawing to occur on the output medium. If this control is set to off, then except for GpiErase, no output operations appear on the output medium. This includes raster operations, such as drawing primitives, and GpiDraw... operations.

DCTL_BOUNDARY (*): Accumulate boundary data. During any output operations except GpiErase, accumulate the bounding rectangle of the drawing.

DCTL_DYNAMIC

Draw dynamic segments. Perform an implicit GpiRemoveDynamics before GpiDrawChain, GpiDrawFrom, or GpiDrawSegment, and an implicit GpiDrawDynamics afterwards.

Note that, to either remove or draw dynamic segments, the system forces the foreground mix to FM_XOR, and the background mix to BM_LEAVEALONE. If the first nondynamic segment being drawn (immediately after the dynamic segments have been removed) has the ATTR_FASTCHAIN attribute (see GpiSetInitialSegmentAttrs), it may be necessary for it to set the mix modes itself before drawing. Similar considerations might apply for any subsequent drawing after the dynamic segments have been replaced.

DCTL_CORRELATE (*): If this control is set, any GpiPutData, GpiElement, GpiPlayMetaFile, or individual drawing primitives which are passed across the API outside a segment bracket cause a correlation operation to be performed, and a return code to be set if a hit occurs. (Correlation inside segments, both retained and nonretained, is controlled by the segment attribute ATTR_DETECTABLE).; This control has an effect only in draw or draw-and-retain modes (see GpiSetDrawingMode).

lValue (LONG) - input

Required value of the drawing control.

DCTL_OFF: Set control off
DCTL_ON: Set control on.

Return Value

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_DRAW_CONTROL (0x2063): An invalid control parameter was specified with GpiSetDrawControl or GpiQueryDrawControl.
PMERR_INV_DRAW_VALUE (0x2064): An invalid value parameter was specified with GpiSetDrawControl.
PMERR_INV_IN_SEG (0x208D): An attempt was made to issue a function invalid inside a segment bracket.
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_MICROPS_DRAW_CONTROL (0x20A0): A draw control parameter was specified with GpiSetDrawControl that is invalid in a micro presentation space.

Remarks

The default value is DCTL_OFF for all controls except DCTL_DISPLAY (*). Its default value is DCTL_ON.

This function must not be issued in any of these cases:

Inside an open segment
Outside an open segment, but inside one of:
- Area bracket
- Element bracket
- Path bracket.

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; see "MetaFile Resolutions" in the Presentation Manager Programming Reference for more information.

Example Code

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

HPS     hps;       /*  Presentation-space handle. */
LONG    lControl;  /*  Drawing control. */
LONG    lValue;    /*  Required value of the drawing control. */
BOOL    rc;        /*  Success indicator. */

rc = GpiSetDrawControl(hps, lControl, lValue);

The "display" drawing control is switched off, and the "accumulate-boundary-data" control is switched on.

#define INCL_GPICONTROL
#include <OS2.H>

HPS hps;         /*   Presentation-space */
                 /*   handle.            */

  GpiResetBoundaryData(hps);
  GpiSetDrawControl(hps, DCTL_DISPLAY, DCTL_OFF);

Related Functions