GpiDeleteElementRange: Difference between revisions

Latest revision as of 00:41, 17 November 2025

This function deletes all elements between, and including, the elements indicated by the specified element numbers.

Syntax

GpiDeleteElementRange(hps, lFirstElement, lLastElement)

Parameters

hps (HPS) - input: Presentation-space handle.
lFirstElement (LONG) - input: Number of the first element to be deleted.; If lFirstElement > lLastElement, the values are swapped before being used.
lLastElement (LONG) - input: Number of the last element to be deleted.; If lLastElement < lFirstElement, the values are swapped before being used.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE - Successful completion

FALSE - Error occurred.

Remarks

If either element number is outside the range of the current segment, it is set to the nearest valid value. When this function has finished, the element pointer is set to the element immediately preceding the deleted element or 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.

Example Code

This example uses the GpiDeleteElementRange function to delete the second through fifth elements in the previously created segment 2.

#define INCL_GPISEGEDITING /* GPI Segment Edit functions */
#include <os2.h>

HPS hps;

GpiOpenSegment(hps, 2L); /* open segment # 2 */
GpiDeleteElementRange(hps, 2L, 5L);/* delete elements 2 thru 5 */
GpiCloseSegment(hps); /* close the segment */

Related Functions

@@ Line 5: / Line 5: @@
 ==Parameters==
-; hps ([[HPS]]) - input
+; hps ([[HPS]]) - input: Presentation-space handle.
-: Presentation-space handle.
+; lFirstElement (LONG) - input: Number of the first element to be deleted.
-; lFirstElement ([[LONG]]) - input
-: Number of the first element to be deleted.
 : If lFirstElement > lLastElement, the values are swapped before being used.
+; lLastElement ([[LONG]]) - input: Number of the last element to be deleted.
-; lLastElement ([[LONG]]) - input
-: Number of the last element to be deleted.
 : If lLastElement < lFirstElement, the values are swapped before being used.
 ==Return Value==
-; rc ([[BOOL]]) - returns
+; rc ([[BOOL]]) - returns: Success indicator.
-: Success indicator.
+:: TRUE - Successful completion
-:; TRUE
+:: FALSE - Error occurred.
-:: Successful completion
-:; FALSE
-:: Error occurred.
 ==Remarks==
@@ Line 31: / Line 23: @@
 ==Errors==
 Possible returns from WinGetLastError:
-; PMERR_INV_HPS (0x207F)
+; PMERR_INV_HPS (0x207F): An invalid presentation-space handle was specified.
-: 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_PS_BUSY (0x20F4)
+; PMERR_INV_MICROPS_FUNCTION (0x20A1): An attempt was made to issue a function that is invalid in a micro presentation space.
-: An attempt was made to access the presentation space from more than one thread simultaneously.
+; 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_INV_MICROPS_FUNCTION (0x20A1)
+; PMERR_NO_CURRENT_SEG (0x20E6): An attempt has been made to issue GpiQueryElementType or GpiQueryElement while there is no currently open segment.
-: An attempt was made to issue a function that is invalid in a micro presentation space.
+; PMERR_INV_IN_ELEMENT (0x2089): An attempt was made to issue a function invalid inside an element bracket.
-; 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.
 ==Example Code==
-<PRE>
-#define INCL_GPISEGEDITING /* Or use INCL_GPI, INCL_PM, */
-#include &lt;os2.h&gt;
-HPS  hps;           /* Presentation-space handle. */
-LONG lFirstElement; /* Number of the first element to be deleted. */
-LONG lLastElement;  /* Number of the last element to be deleted. */
-BOOL rc;            /* Success indicator. */
-rc = GpiDeleteElementRange(hps, lFirstElement, lLastElement);
-</PRE>
 This example uses the GpiDeleteElementRange function to delete the second through fifth elements in the previously created segment 2.
 <pre>
 #define INCL_GPISEGEDITING /* GPI Segment Edit functions */
-#include &lt;os2.h&gt;
+#include <os2.h>
 HPS hps;