GpiQueryTextBox

This function returns the relative coordinates of the four corners of a text box.

Syntax

GpiQueryTextBox(hps, lCount1, pchString, lCount2, aptlPoints)

Parameters

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

lCount1 (LONG) - input: Number of characters.; It must be greater or equal to 0 and less or equal to 512

pchString (PCH) - input: The character string.

lCount2 (LONG) - input: Number of points.; Contains the number of points to be returned in the aptlPoints array. Specify TXTBOX_COUNT to get the maximum information. This parameter must be greater or equal to 0.

aptlPoints (PPOINTL) - output: List of points.; The list of points contains the relative coordinates of the text box in world coordinates. The array elements are numbered consecutively, starting with TXTBOX_TOPLEFT. A lCount2 value of TXTBOX_COUNT will cause all of the defined array elements to be returned.; The terms 'top-left', 'bottom-right', and so on, are well defined when the character angle is such that the baseline is parallel to the x axis and running left to right, and there is no character shear. If the character string is rotated or sheared, the term top-left applies to the corner of the box that appears in the top-left position when no rotation or shear is applied.; This is an example:; Set character angle = -1,1; String = ABCDE; Coordinates returned are as shown:

The possible values for this parameter are:

TXTBOX_TOPLEFT: Top-left corner
TXTBOX_BOTTOMLEFT: Bottom-left corner
TXTBOX_TOPRIGHT: Top-right corner
TXTBOX_BOTTOMRIGHT: Bottom-right corner
TXTBOX_CONCAT: Concatenation point.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE: Successful completion
FALSE: Error occurred.

Remarks

The text box is defined as the parallelogram that encloses the specified character string when displayed on the device. Also returned are the relative coordinates of the concatenation point; that is, the value of current position after an equivalent GpiCharStringAt function. All coordinates are relative to the start point. (See GpiSetCharDirection function.) These coordinates can be used to box or underline the string, or to change the attributes in the middle of a longer string. Note: The height of the string is based on the maximum height of the font (including space for descenders, accents, and so on), not the maximum height of the actual characters in the string. The dimensions of the box do not correspond directly to those of the character box (see GpiSetCharBox). Character attributes are taken into account as if the string is to be drawn, but no output actually occurs. However, if the character mode (see GpiSetCharMode) is CM_MODE2 this function should only be used if the character angle (see GpiSetCharAngle), character direction (see GpiSetCharDirection) and character shear (see GpiSetCharShear) attributes are set to their default values. This function is not valid when the drawing mode (see GpiSetDrawingMode) is set to retain.

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_IN_RETAIN_MODE (0x208C): An attempt was made to issue a function (for example, query) that is invalid when the actual drawing mode is not draw or draw-and-retain.
PMERR_INV_LENGTH_OR_COUNT (0x2092): An invalid length or count parameter was specified.
PMERR_COORDINATE_OVERFLOW (0x2014): An internal coordinate overflow error occurred. This can occur if coordinates or matrix transformation elements (or both) are invalid or too large.
PMERR_INV_DC_TYPE (0x2060): An invalid type parameter was specified with DevOpenDC, or a function was issued that is invalid for a OD_METAFILE_NOQUERY device context.

Example Code

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

HPS       hps;        /* Presentation-space handle. */
LONG      lCount1;    /* Number of characters. */
PCH       pchString;  /* The character string. */
LONG      lCount2;    /* Number of points. */
PPOINTL   aptlPoints; /* List of points. */
BOOL      rc;         /* Success indicator. */

rc = GpiQueryTextBox(hps, lCount1, pchString, lCount2, aptlPoints);

This example uses the GpiQueryTextBox function to draw a line under the string. The GpiCharString function draws the string at the point (100,100). Since the points retrieved by GpiQueryTextBox are relative to the start of the string, the starting point needs to be added to the points that are used to draw the underline.

#define INCL_GPIPRIMITIVES
#include <OS2.H>

HPS hps;
POINTL aptl[TXTBOX_COUNT];
POINTL ptl = { 100, 100 };

GpiQueryTextBox(hps, 11L, "This string", TXTBOX_COUNT, aptl); /* array of coordinates points */
                                                              /* in world coordinates. */

aptl[1].x += ptl.x;
aptl[1].y += ptl.y;
GpiMove(hps, &aptl[1]);

aptl[3].x += ptl.x;
aptl[3].y += ptl.y;
GpiLine(hps, &aptl[3]);

GpiMove(hps, &ptl);
GpiCharString(hps, 11L, "This string");