View source for GpiRemoveDynamics

This function removes those parts of the displayed image that are drawn from the dynamic segments in a section of the segment chain. This includes any parts that are drawn by calls from these dynamic segments.

==Syntax==
 GpiRemoveDynamics(hps, lFirstSegid, lLastSegid)

==Parameters==
; hps ([[HPS]]) - input
: Presentation-space handle.

; lFirstSegid ([[LONG]]) - input
: First segment in the section.
: It must be greater than 0.

; lLastSegid ([[LONG]]) - input
: Last segment in the section.
: It must be greater than 0.

==Return Value==
; rc ([[BOOL]]) - returns
: Success indicator.
:; TRUE
:: Successful completion
:; FALSE
:: Error occurred.

==Remarks==
This function usually indicates that a dynamic segment is about to be updated; and that, having completed the update, [[GpiDrawDynamics]] is called to redraw the dynamic segments.

If there is more than one dynamic segment, only those that are being updated need be removed. The section of the segment chain is identified by the first and last segments in the section. If lFirstSegid and lLastSegid have the same value, this call erases only the parts drawn from the segment, and by calls from that segment.

Specifying the range of segment identifiers that are to be removed usually has a performance advantage, in that searching of the chain stops after lLastSegid has been processed. It can also be used to operate on less than the maximum number of dynamic segments, as in one of the following examples:
* Several dynamic segments are currently drawn, but only one is to be updated. Identifying this segment with both lFirstSegid and lLastSegid means that only this one is removed. It can then be updated, and replaced with [[GpiDrawDynamics]].
* A new dynamic segment can be created, while the rest remain drawn. [[GpiRemoveDynamics]] is issued before the segment has been created (or while it is unchained, if it already exists), identifying it with both lFirstSegid and lLastSegid. It is then created with this identifier (or chained, if it already exists), and [[GpiDrawDynamics]] is issued, causing it to be drawn.

In these examples, the other dynamic segments remain drawn throughout.

In all cases, after [[GpiDrawChain]], [[GpiDrawDynamics]], [[GpiDrawFrom]], or [[GpiDrawSegment]], where the DCTL_DYNAMIC draw control is set (see [[GpiSetDrawControl]]), all dynamic segments must be drawn. The lFirstSegid and lLastSegid parameters of GpiRemoveDynamics, cannot be used to cause a subset of dynamic segments to be drawn after the following [[GpiDrawDynamics]]. If this is required, it can be done by unchaining the unwanted dynamic segments after first removing them.

Dynamic segments that are currently drawn must never be updated in the segment store, nor must any drawing in mix modes (other than exclusive-OR or leave-alone) be done to a presentation space while dynamic segments are drawn in it.

If a temporary re-association is to be done, this function must be issued to remove the dynamic segments from the display before the first dissociation.
It is necessary to ensure that attributes, model transform, current position, and viewing limits are reset to their default values, before processing the segments. This can either be done by ensuring that the first dynamic segment in the removed section does not have the ATTR_FASTCHAIN attribute (see [[GpiSetInitialSegmentAttrs]]), or by issuing [[GpiResetPS]] before the GpiRemoveDynamics. The latter method also resets the clip path to cause no clipping, which may also be necessary.

If this function is followed by primitives or attributes, without first opening a segment, the processing is as described for [[GpiCloseSegment]].

In particular, note that during GpiRemoveDynamics, the system forces the foreground mix to FM_XOR and the background mix to BM_LEAVEALONE. It may be necessary to set one or both of these before starting to draw.

If lFirstSegid does not exist, or is not in the segment chain, no removal or drawing occurs. However, the segment identifier range is still established for a subsequent [[GpiDrawDynamics]] function.

If lLastSegid does not exist, or is not in the chain, or is chained before lFirstSegid, no error is raised, and processing continues to the end of the chain.

==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_SEG_NAME (0x20C8)
: An invalid segment identifier was specified.
; PMERR_INV_FOR_THIS_DC_TYPE (0x2074)
: An attempt has been made to issue GpiRemoveDynamics or GpiDrawDynamics to a presentation space associated with a metafile device context.

==Example Code==
<PRE>
#define INCL_GPISEGMENTS /* Or use INCL_GPI, INCL_PM, */
#include &lt;os2.h&gt;

HPS  hps;         /* Presentation-space handle. */
LONG lFirstSegid; /* First segment in the section. */
LONG lLastSegid;  /* Last segment in the section. */
BOOL rc;          /* Success indicator. */

rc = GpiRemoveDynamics(hps, lFirstSegid, lLastSegid);
</PRE>

This example uses the GpiRemoveDynamics function to remove the image drawn by the dynamic segment whose segment identifier is 4. It then edits the segment and redraws it, using the GpiDrawDynamics function.

<pre>
#define INCL_GPISEGMENTS
#define INCL_GPICONTROL
#include &lt;OS2.H&gt;

POINTL ptl = {30, 40};
HPS hps; /* presentation space handle */

/* Remove the image for dynamic segment #4. */
GpiRemoveDynamics(hps, 4L, 4L);

/* Edit the segment. */
GpiSetDrawingMode(hps,DM_RETAIN);
GpiOpenSegment(hps, 4L);
GpiSetElementPointer(hps, 1L);
GpiMove(hps, &ptl);
GpiCloseSegment(hps);

GpiDrawDynamics(hps); /* redraws the edited segment */
</pre>

==Related Functions==
* [[GpiDrawChain]]
* [[GpiDrawDynamics]]
* [[GpiDrawFrom]]
* [[GpiDrawSegment]]
* [[GpiErase]]
* [[GpiGetData]]
* [[GpiPutData]]
* [[GpiSetDrawControl]]
* [[GpiSetDrawingMode]]
* [[GpiSetStopDraw]]

[[Category:Gpi]]