GreGetPairKerningTable

GreGetPairKerningTable stores the kerning pairs of the current font to the buffer addressed by pKernPairs.

This function must be supported by the presentation driver. The call parameters are passed unchanged to the display driver's dispatch table. GreGetPairKerningTable is called from GpiQueryKerningPairs. GreGetPairKerningTable is used to return the kerning data for the currently selected font. This function can be handled by bit-map simulation.

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

Syntax

GreGetPairKerningTable(hdc, cKernPairs, pKernPairs, pInstance, lFunction);

Parameters

hdc (HDC) - input: Device context handle.

cKernPairs (LONG) - input: Number of kerning pairs requested by the application.

pKernPairs (PKERNPAIRS) - input

Pointer to kerning pair records.

KERNINGPAIRS data structure:

sFirstChar Code point for the first character
sSecondChar Code point for the second character
sKerningAmount Two-byte signed integer indicating the amount of kerning. Positive numbers specify increased inter-character spacing.

pInstance (PVOID) - input: Pointer to instance data.

lFunction (ULONG) - input: High-order WORD=flags;. low-order WORD=NGreGetPairKerningTable.

Returns

rc (LONG) - returns: Return Code.

On completion, the handling routine must return the number of kerning pairs returned in pKernPairs (cPairs), or GPI_ALTERROR if an error occurs.

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_CODEPAGE
PMERR_INV_COORD_SPACE
PMERR_INV_HDC
PMERR_INV_LENGTH_OR_COUNT
PMERR_INV_SETID

Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Sample

#define INCL_GRE_DEVMISC1
#include <os2.h>

HDC           hdc;         /*  Device context handle. */
LONG          cKernPairs;  /*  Number of kerning pairs requested by the application. */
PKERNPAIRS    pKernPairs;  /*  Pointer to kerning pair records. */
PVOID         pInstance;   /*  Pointer to instance data. */
ULONG         lFunction;   /*  High-order WORD=flags;. low-order WORD=NGreGetPairKerningTable. */
LONG          rc;          /*  Return Code. */

rc = GreGetPairKerningTable(hdc, cKernPairs,
       pKernPairs, pInstance, lFunction);

Remarks

The handling routine must transform all kerning-pair coordinates from device to world coordinates before sending the data to the calling routine. This can be done by using GreConvert. If it is unable to do this because the transform matrix is singular, it must log PMERR_COORDINATE_OVERFLOW.

The number of kerning pairs is a field in the FONTMETRICS structure.