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
#define INCL_GPISEGMENTS /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> 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);
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.
#define INCL_GPISEGMENTS
#define INCL_GPICONTROL
#include <OS2.H>
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 */