GpiSetElementPointer

This function sets the element pointer, within the current segment, to the element number specified.

Syntax

GpiSetElementPointer(hps, lElement)

Parameters

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

lElement (LONG) - input: The element number required.; If the value specified is negative, the element pointer is set to 0.; If the value specified is greater than the number of elements in the segment, the element pointer is set to the last element.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE: Successful completion
FALSE: Error occurred.

Remarks

The currently open segment has an element pointer that points to a particular element in the segment; each element is placed into the segment at the place indicated by the pointer. When a retained segment is first opened, the element pointer is set to 0 (empty segment). It is incremented each time a call causes an element (a single API call) to be placed in the segment. When a segment is reopened, the element pointer is reset to 0 (that is, before the first element). The element pointer for a segment is not remembered if the segment is closed and subsequently reopened. 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_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_MICROPS_FUNCTION (0x20A1): 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.

Related Functions

Example Code

#define INCL_GPISEGEDITING /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS  hps;      /* Presentation-space handle. */
LONG lElement; /* The element number required. */
BOOL rc;       /* Success indicator. */

rc = GpiSetElementPointer(hps, lElement);

This function sets the element pointer, within the current segment, to 0.

#define INCL_GPICONTROL
#define INCL_GPISEGEDITING
#include <OS2.H>

HPS hps; /* Presentation-space */
/* handle. */

/* This example uses the GpiSetElementPointer function to move */
/* the element pointer to an element to be edited. */

GpiSetDrawingMode(hps, DM_RETAIN);/* set DM_RETAIN drawing mode */
GpiOpenSegment(hps, 2L); /* open segment to edit */
GpiSetElementPointer(hps, 3L); /* move element pointer
                                  to 3rd element */
GpiSetColor(hps,CLR_GREEN); /* new element changes
                               color to green */
GpiCloseSegment(hps); /* close the segment */