GreDeviceQueryFonts

GreDeviceQueryFonts returns the characteristics of device fonts in an array of FONTMETRICS structures, if the QF_PUBLIC option flag (see the flOptions parameter) is set. The returned fonts include those that correspond to device modes such as "expanded" and "expanded-bold".

This function must be supported by the presentation driver.

Simulation support

None. This function is mandatory for all drivers.

Syntax

GreDeviceQueryFonts(hdc, flOptions, pszFaceName, pfmMetrics,
                    cMetrics, pcFonts, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

flOptions (ULONG) - input

Option flags.

The only valid flag for this function is:

QF_PUBLIC - When this flag is set, the handling routine must return all device fonts. "Device fonts" are public fonts and they are returned in the array addressed by pfmMetrics. If this flag is not set, the handling routine should not return any fonts.

pszFaceName (PSZ) - input

Pointer to FaceName to match.

If this is a NULL pointer, all faces are matched.

pfmMetrics (PFONTMETRICS) - input

Pointer to array of FONTMETRICS structures.

cMetrics (LONG) - input

Number of bytes of each metrics structure in the metrics array.

pcFonts (PLONG) - input

Pointer to the number of fonts requested.

This is a pointer to the number of fonts requested. On completion, the handling routine modifies the value indicated to the number of fonts returned. An application can determine the number of public fonts available to it by passing a value of 0 at the address indicated by this pointer.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreDeviceQueryFonts.

Return Code

rc (LONG) - returns

Return Codes.

The handling routine should return the number of fonts not returned or else return GPI_ALTERROR if an error occurred.

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_DEV_FUNC_NOT_INSTALLED
• PMERR_INV_HDC

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

Remarks

When the device context is not set to draft mode, the returned fonts are those that can be positioned to the nearest pel. Such precision is not necessary if the device context is in draft mode. Draft mode is set by the system calling the GreEscape DEVESC_DRAFTMODE.

In the FONTMETRICS structures, the handling routine sets:

• szFacename field to a meaningful name, such as 'Courier Bold'.
• usCodepage field to 0. (This field has no significance in this context.)
• lMatch field to a negative value. This allows the presentation driver to map the font when the value is specified in a call to GreRealizeFont.

The presentation driver must transform device coordinates to world coordinates before it returns the results to the calling routine. This can be done by using GreConvert. For presentation drivers that support only outline fonts, the return values are for outline fonts even when image fonts have been loaded.

Sample Code

#define INCL_GRE_DEVMISC2
#include <os2.h>

HDC             hdc;         /*  Device context handle. */
ULONG           flOptions;   /*  Option flags. */
PSZ             pszFaceName; /*  Pointer to FaceName to match. */
PFONTMETRICS    pfmMetrics;  /*  Pointer to array of FONTMETRICS structures. */
LONG            cMetrics;    /*  Number of bytes of each metrics structure in the metrics array. */
PLONG           pcFonts;     /*  Pointer to the number of fonts requested. */
PVOID           pInstance;   /*  Pointer to instance data. */
ULONG           lFunction;   /*  High-order WORD=flags; low-order WORD=NGreDeviceQueryFonts. */
LONG            rc;          /*  Return Codes. */

rc = GreDeviceQueryFonts(hdc, flOptions, pszFaceName,
       pfmMetrics, cMetrics, pcFonts, pInstance,
       lFunction);