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