View source for GpiDeleteElementsBetweenLabels

This function deletes all elements between, but not including, the elements found to contain the indicated labels.

==Syntax==
 GpiDeleteElementsBetweenLabels(hps, lFirstLabel, lLastLabel)

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

; lFirstLabel ([[LONG]]) - input
: Label marking the start of the elements to be deleted.
: It must be greater or equal to 0.

; lLastLabel ([[LONG]]) - input
: Label marking the end of the elements to be deleted.
: It must be greater or equal to 0.

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

==Remarks==
The search for lFirstLabel and lLastLabel is performed separately, and starts from the element pointed to by the current element pointer.
See also:
* [[GpiSetElementPointer]]
* [[GpiSetElementPointerAtLabel]].
If either label cannot be found between the current element pointer location and the end of the segment, an error is generated and no deletion occurs.
On completion, the element pointer is set to the element immediately preceding the deleted elements.
This function is only valid when the drawing mode (see [[GpiSetDrawingMode]]) is set to retain (not draw-and-retain), and a segment bracket is currently in progress. It is not valid within an element bracket.

==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_NOT_IN_RETAIN_MODE (0x20E2)
: An attempt was made to issue a segment editing element function that is invalid when the actual drawing mode is not set to retain.
; PMERR_NO_CURRENT_SEG (0x20E6)
: An attempt has been made to issue GpiQueryElementType or GpiQueryElement while there is no currently open segment.
; PMERR_INV_IN_ELEMENT (0x2089)
: An attempt was made to issue a function invalid inside an element bracket.
; PMERR_LABEL_NOT_FOUND (0x20D6)
: The specified element label did not exist.


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

HPS  hps;         /* Presentation-space handle. */
LONG lFirstLabel; /* Label marking the start of the elements to be deleted. */
LONG lLastLabel;  /* Label marking the end of the elements to be deleted. */
BOOL rc;          /* Success indicator. */

rc = GpiDeleteElementsBetweenLabels(hps, lFirstLabel, lLastLabel);
</PRE>

This example uses the GpiDeleteElementsBetweenLabels function to delete the elements between, but not including, the elements having the labels 1 and 2.

<pre>
#define INCL_GPISEGEDITING /* GPI Segment Edit functions */
#include &lt;os2.h&gt;

HPS hps;

GpiOpenSegment(hps, 2L); /* open segment #2 */
/* delete elements between 1 and 2 */
GpiDeleteElementsBetweenLabels(hps, 1L, 2L);
GpiCloseSegment(hps); /* close the segment */
</pre>

==Related Functions==
* [[GpiBeginElement]]
* [[GpiDeleteElement]]
* [[GpiDeleteElementRange]]
* [[GpiElement]]
* [[GpiEndElement]]
* [[GpiLabel]]
* [[GpiOffsetElementPointer]]
* [[GpiQueryElement]]
* [[GpiQueryElementPointer]]
* [[GpiQueryElementType]]
* [[GpiSetElementPointer]]
* [[GpiSetElementPointerAtLabel]]


[[Category:Gpi]]