GreQueryTextBox

From EDM2
Jump to: navigation, search

GreQueryTextBox processes a character string as if it were being drawn.

This function must be supported by the presentation driver. GreQueryTextBox is called by the function GpiQueryTextBox, and is used to return a tight bounding box for the currently selected font of a given string relative to the current position.

Simulation support
None. This function is mandatory for all drivers.


Syntax

GreQueryTextBox(hdc, cChars, pchString,
      cptPosition, paptPosition, pInstance, lFunction)

Parameters

hdc (HDC) - input
Device context handle.
cChars (LONG) - input
Number of bytes in string.
pchString (PCH) - input
Pointer to character string.
cptPosition (LONG) - input
Number of (X, Y) pairs that the Position array can contain.
paptPosition (PPOINTL) - input
Pointer to position array.
Pointer to the array in which the function returns the requested values. Upon completion, the array contains cptPosition sets of (X, Y) coordinates in the following order:
TXTBOX_TOPLEFT
Top-left corner
TXTBOX_BOTTOMLEFT
Bottom-left corner
TXTBOX_TOPRIGHT
Top-right corner
TXTBOX_BOTTOMRIGHT
Bottom-right corner
TXTBOX_CONCAT
Start point of next character position
pInstance (PVOID) - input
Pointer to instance data.
lFunction (ULONG) - input
High-order WORD=flags; low-order WORD=NGreQueryTextBox.

Return Code

rc (BOOL) - returns
Return Code.
On completion, the handling routine must return a BOOLEAN value to indicate success or an error.
  • TRUE Successful
  • FALSE Error
Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:
  • PMERR_COORDINATE_OVERFLOW
  • PMERR_DEV_FUNC_NOT_INSTALLED
  • PMERR_EXCEEDS_MAX_SEG_LENGTH
  • PMERR_HDC_BUSY
  • PMERR_INSUFFICIENT_MEMORY
  • PMERR_INV_CHAR_ANGLE_ATTR
  • PMERR_INV_CHAR_MODE_ATTR
  • PMERR_INV_CODEPAGE
  • PMERR_INV_COORD_SPACE
  • PMERR_INV_HDC
  • PMERR_INV_LENGTH_OR_COUNT
  • PMERR_INV_MATRIX_ELEMENT
  • PMERR_INV_SETID
  • PMERR_INV_TRANSFORM_TYPE
Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Remarks

The handling routine stores the coordinates of the current text box (relative to the current (X,Y) position) as an array at the location indicated by paptPosition. The first four coordinate pairs identify the bounding parallelogram for the given character string. The fifth coordinate pair is the (X,Y) position of the starting point for the next character position after the string, that is, the current position value that would be set by an equivalent call to GpiCharStringAt. The positions take account of current values for character spacing such as kerning and character space. The points on the borders of the character box are deemed to be inside the box.

When the character mode is CM_MODE2, this function is valid only if the character angle and shear attributes are set to their default values. See Character Attributes.

Sample Code

#define INCL_GRE_STRINGS
#include <os2.h>

HDC        hdc;           /*  Device context handle. */
LONG       cChars;        /*  Number of bytes in string. */
PCH        pchString;     /*  Pointer to character string. */
LONG       cptPosition;   /*  Number of (X, Y) pairs that the Position array can contain. */
PPOINTL    paptPosition;  /*  Pointer to position array. */
PVOID      pInstance;     /*  Pointer to instance data. */
ULONG      lFunction;     /*  High-order WORD=flags; low-order WORD=NGreQueryTextBox. */
BOOL       rc;            /*  Return Code. */

rc = GreQueryTextBox(hdc, cChars, pchString,
       cptPosition, paptPosition, pInstance, lFunction);