Jump to content

GpiQueryFonts

From EDM2

This function returns a record providing details of the fonts that match the specified pszFacename.

Syntax

GpiQueryFonts(hps, flOptions, pszFacename, plReqFonts, lMetricsLength, afmMetrics)

Parameters

hps (HPS) - input
Presentation-space handle.
flOptions (ULONG) - input
Enumeration options.
This controls which fonts are to be enumerated. If more than one of the following options are required, the values can be ORed together.
QF_PUBLIC
Enumerate public fonts.
QF_PRIVATE
Enumerate private fonts.
QF_NO_DEVICE
Device fonts are not reported.
QF_NO_GENERIC
Generic fonts are not reported.
pszFacename (PSZ) - input
Face name of fonts.
If the pointer to pszFacename is NULL, all available fonts are queried, regardless of their face names.
plReqFonts (PLONG) - in/out
Count of fonts.
The number of fonts for which the application requires the metrics. This variable returns the number of fonts returned.
lMetricsLength (LONG) - input
Length of metrics.
The length of each metrics record to be returned. The afmMetrics data area must be plReqFonts multiplied by lMetricsLength long.
afmMetrics (PFONTMETRICS) - output
Metrics of font.
In this structure are returned the font metrics of up to plReqFonts matching fonts. The format for each record is as defined for GpiQueryFontMetrics, except that the usCodePage field has no meaning in this context, and is indeterminate. For each font, no more data than lMetricsLength is returned.

Return Value

lRemFonts (LONG) - returns
Count of fonts not returned.
>=0
Count of fonts not returned
GPI_ALTERROR
Error.

Remarks

Font metrics are returned for as many matching fonts as can be held in afmMetrics. By inspecting the returned data, the application can choose which of the available fonts is most appropriate for its requirements. If necessary, it can force selection of a particular font, by specifying its match (as returned in afmMetrics) in the pfatAttrs structure for GpiCreateLogFont, however, this is only valid for a particular device/device driver combination on a single machine. This method should be avoided as a method for selecting a font. An application can determine if the font szFacename (as returned in afmMetrics) has been truncated by checking the fsType field in afmMetrics for the FM_TYPE_FACETRUNC indicator. If the face name has been truncated, this bit will be set, and the application can issue a WinQueryAtomName function, passing in the FaceNameAtom (as returned in afmMetrics) to retrieve the full face name from the System Atom table. By specifying plReqFonts as 0, and then looking at the value returned in lRemFonts, an application can determine how many fonts there are that match the pszFacename. All sizes are returned in world coordinates.

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_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.

Example Code

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

HPS            hps;            /* Presentation-space handle. */
ULONG          flOptions;      /* Enumeration options. */
PSZ            pszFacename;    /* Face name of fonts. */
PLONG          plReqFonts;     /* Count of fonts. */
LONG           lMetricsLength; /* Length of metrics. */
PFONTMETRICS   afmMetrics;     /* Metrics of font. */
LONG           lRemFonts;      /* Count of fonts not returned. */

lRemFonts = GpiQueryFonts(hps, flOptions, pszFacename, plReqFonts, lMetricsLength, afmMetrics);

This example uses the GpiQueryFonts function to retrieve the font metrics for all private fonts having the "Helv" typeface name. The function is called twice, first to determine the number of fonts available, and then again to retrieve the font metrics for all the fonts.

#define INCL_GPILCIDS /* Font functions */
#define INCL_DOSMEMMGR /* DOS Memory Manager Functions */
#include <os2.h>

HPS hps; /* presentation space handle */
LONG cFonts; /* fonts not returned */
LONG lTemp = 0L; /* font count */
PFONTMETRICS pfm; /* metrics structure */

/* Determine the number of fonts. */
cFonts = GpiQueryFonts(hps, QF_PRIVATE, "Helv", &lTemp, (LONG) sizeof(FONTMETRICS), NULL);

/* Allocate space for the font metrics. */
DosAllocMem((VOID *)pfm,(ULONG)(cFonts*sizeof(FONTMETRICS)), PAG_COMMIT | PAG_READ | PAG_WRITE);

/* Retrieve the font metrics. */
cFonts = GpiQueryFonts(hps, QF_PRIVATE, "Helv", &cFonts, (LONG) sizeof(FONTMETRICS), pfm);