GpiQueryFaceString

This function generates a compound face name for a font.

Syntax

GpiQueryFaceString(ps, FamilyName, attrs, length, CompoundFaceName)

Parameters

ps (HPS) - input: Presentation-space handle.

FamilyName (PSZ) - input: Family name.; The family name of the font (for example, "Courier").

attrs (PFACENAMEDESC) - input: Face-name description.; A structure that provides the characteristics of the required font. These characteristics are used to generate the compound face name.

length (LONG) - input: Length of CompoundFaceName buffer.; The maximum length of the compound face name returned (including the trailing zero of the string).; Specify zero to find out how large the CompoundFaceName buffer needs to be.

CompoundFaceName (PSZ) - output: Compound face name.; The compound face name of the font.

Return Value

cbRetLength (ULONG) - returns

Length of the compound face name.

GPI_ERROR: Error occurred
> 0: Length of the compound face-name string (including the trailing zero). This is the length of the complete string; if it is greater than length, the string returned in CompoundFaceName is truncated.

Remarks

This function generates a compound face name (for example, "Courier Bold Italic") from a family name (for example, "Courier"). The compound face name can be used on a GpiCreateLogFont function.

Errors

Possible returns from WinGetLastError:

PMERR_FONT_NOT_LOADED (0x202F): An attempt was made to create a font that was not loaded.
PMERR_INV_FACENAME (0x210E): An invalid font family name was passed to GpiQueryFaceString.
PMERR_INV_FACENAMEDESC (0x2115): The font facename description is invalid.
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.

Example Code

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

HPS             ps;                /* Presentation-space handle. */
PSZ             FamilyName;        /* Family name. */
PFACENAMEDESC   attrs;             /* Face-name description. */
LONG            length;            /* Length of buffer. */
PSZ             CompoundFaceName;  /* Compound face name. */
ULONG           cbRetLength;       /* Length of the compound face name. */

cbRetLength = GpiQueryFaceString(ps, FamilyName, attrs, length, CompoundFaceName);

In this example GpiQueryFaceString is used to generate a compound face name of "Courier Bold Italic" from the family name "Courier."

#define INCL_GPILCIDS /* Font functions */
#include <os2.h>

ULONG cbRetLength; /* length of compound face name */
HPS hps; /* Presentation-space handle */
char pszFamilyName[13];/* Family name */
FACENAMEDESC pfndFaceAttrs; /* Face-name description */
LONG lLength; /* length of buffer */
char pszCompoundFaceName[25];/* Compound face name */

/* family name is 'Courier' */
strcpy(pszFamilyName,"Courier");

/* let the function determine the buffer length and return it */
lLength = 25L;

/* initialize face name description structure for bold weight class, normal width, and italics */
pfndFaceAttrs.usSize = sizeof(FACENAMEDESC); /* Length of structure */
pfndFaceAttrs.usWeightClass = FWEIGHT_BOLD; /* Weight class */
pfndFaceAttrs.usWidthClass = FWIDTH_NORMAL; /* Width class */
pfndFaceAttrs.usReserved = 0; /* Reserved */
pfndFaceAttrs.flOptions = FTYPE_ITALIC; /* Other characteristics of the font */

cbRetLength = GpiQueryFaceString(hps, pszFamilyName, &pfndFaceAttrs, lLength, pszCompoundFaceName);