GreQueryTextBox
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);