GpiComment

Description

This function adds a comment to the current segment.

Syntax

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

HPS      hps;      /*  Presentation-space handle. */
LONG     lLength;  /*  Data length. */
PBYTE    pbData;   /*  Comment string. */
BOOL     rc;       /*  Success indicator. */

rc = GpiComment(hps, lLength, pbData);

Parameters

hps (HPS) - input: Presentation-space handle.
lLength (LONG) - input: Data length.; The length of pbData in bytes. lLength must >= 0 and <= 255.
pbData (PBYTE) - input: Comment string.; No conversion of any kind is performed on the data.

Return Code

rc (BOOL) - returns

Success indicator.

TRUE Successful completion
FALSE Error occurred.

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_LENGTH_OR_COUNT (0x2092) : An invalid length or count parameter was specified.

Graphic Elements and Orders

Element Type: OCODE_GCOMT
Order: Comment

Remarks

An application can use this function to store some data of its own in the segment if the drawing mode (see GpiSetDrawingMode) is set to retain or draw-and-retain. It has no effect on drawing. The data can subsequently be retrieved by the application using GpiQueryElement or GpiGetData.

Example Code

This example uses the GpiComment function to comment the contents of a segment.

#define INCL_GPIPRIMITIVES      /* GPI primitive functions      */
#define INCL_GPISEGMENTS        /* Segment functions            */
#include <os2.h>

HPS hps;                /* presentation space handle            */
POINTL ptlStart = { 0, 0 }; /* first vertex                     */
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices  */

GpiOpenSegment(hps, 0L);                   /* open the segment  */
GpiComment(hps, 18L, "Start point (0, 0)");
GpiMove(hps, &ptlStart);
GpiComment(hps, 13L, "Draw triangle");
GpiPolyLine(hps, 3L, ptlTriangle);
GpiCloseSegment(hps);                      /* close the segment */