GpiSetElementPointerAtLabel
This function sets the element pointer, within the current segment, to the element containing the specified label.
Syntax
GpiSetElementPointerAtLabel(hps, lLabel)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- lLabel (LONG) - input
- Required label.
Return Value
- rc (BOOL) - returns
- Success indicator.
- TRUE
- Successful completion
- FALSE
- Error occurred.
Remarks
The search starts from the element pointed to by the current element pointer. If the specified label is not found between there and the end of the segment, an error is generated and the element pointer is left unchanged. (Also see GpiSetElementPointer.) This function is valid only when the drawing mode (see GpiSetDrawingMode) is set to retain (not draw-and-retain), and a segment bracket is currently open. 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
#define INCL_GPISEGEDITING /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> HPS hps; /* Presentation-space handle. */ LONG lLabel; /* Required label. */ BOOL rc; /* Success indicator. */ rc = GpiSetElementPointerAtLabel(hps, lLabel);
This function sets the element pointer at label 1.
#define INCL_GPISEGEDITING #include <OS2.H> HPS hps; /* Presentation-space */ /* handle. */ GpiSetElementPointerAtLabel(hps, 1L);