GpiDeleteElement: Difference between revisions

Latest revision as of 00:37, 24 November 2025

This function deletes the element indicated by the element pointer, that was set with GpiSetElementPointer or GpiSetElementPointerAtLabel.

Syntax

GpiDeleteElement(hps)

Parameters

hps (HPS) - input: Presentation-space handle.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE : Successful completion

FALSE : Error occurred.

Remarks

The element pointer is set to the element immediately preceding the deleted element. If the element pointer has a value of 0 (points that are logically before the first element), nothing is deleted and the element pointer is not changed. 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 invalid 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.

Related Functions

Example Code

This example uses the GpiDeleteElement function to delete the third element from the previously created segment 2.

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

HPS hps;

GpiOpenSegment(hps, 2L); /* open segment #2 */
GpiSetElementPointer(hps, 3L); /* move to third element */
GpiDeleteElement(hps); /* delete element */
GpiCloseSegment(hps); /* close the segment */

@@ Line 5: / Line 5: @@
 ==Parameters==
-; ''hps'' ([[HPS]]) - input
+; ''hps'' ([[HPS]]) - input: Presentation-space handle.
-: Presentation-space handle.
 ==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 23: / Line 19: @@
 ==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.
 ==Related Functions==
@@ Line 51: / Line 41: @@
 ==Example Code==
-<PRE>
-#define INCL_GPISEGEDITING /* Or use INCL_GPI, INCL_PM, */
-#include &lt;os2.h&gt;
-HPS  hps; /* Presentation-space handle. */
-BOOL rc;  /* Success indicator. */
-rc = GpiDeleteElement(hps);
-</PRE>
 This example uses the GpiDeleteElement function to delete the third element from the previously created segment 2.
 <pre>
 #define INCL_GPISEGEDITING /* GPI Segment Edit functions */
-#include &lt;os2.h&gt;
+#include <os2.h>
 HPS hps;