GreCreateLogicalFont
GreCreateLogicalFont sets the local identifier (lcid) for a logical font.
This function is supported by the graphics engine.
Contents
Syntax
GreCreateLogicalFont(hdc, lcid, pchName, pAttrs, pInstance, lFunction);
Parameters
- hdc (HDC) - input
- Device context handle.
- lcid (LONG) - input
- Local identifier that is to be assigned to the font.
- pchName (PSTR8) - input
- Pointer.
- Pointer to an eight-character name used to describe the logical font.
- pAttrs (PFATTRS) - input
- Pointer.
- Pointer to a FATTRS structure containing the font attributes:
- usRecordLength
- Length in bytes of this structure
- fsSelection
- Flags that can be set to define those features to be simulated by the system:
- FATTR_SEL_ITALIC Italic characters are required.
- FATTR_SEL_UNDERSCORE Underscored characters are required.
- FATTR_SEL_STRIKEOUT Strikeout characters are required.
- FATTR_SEL_BOLD Bold characters are required.
- lMatch
- The match number for the font. GreQueryFonts returns a unique match number for each font that, together with szFaceName, can be used for font selection. If the match number is negative, a device font is selected. If it is positive, an engine font is selected.
- szFaceName
- The typeface name to which the font is designed. If the szFaceName is provided, an attempt is made to select the font with that face name. If the szFaceName is blank (0 length or NULL), then a default font is used.
- idRegistry
- The Registry number for the font. This should be set to the value returned by GreQueryFonts.
- usCodePage
- Defines the code page supported by the font.
- lMaxBaselineExt
- The required (average) height above the baseline for uppercase characters in world coordinates. For outline and transformable fonts (FATTR_FONTUSE_OUTLINE and FATTR_FONTUSE_TRANSFORM), lMaxBaselineExt should be set to 0.
- lAveCharWidth
- For image fonts, the required average intercharacter increment for the font in world coordinates. For outline and transformable fonts (FATTR_FONTUSE_OUTLINE and FATTR_FONTUSE_TRANSFORM), lAveCharWidth should be set to 0.
- fsType
- Type indicator. Setting fsType to FATTR_TYPE_KERNING indicates that kerning is to be used if the font provides kerning information.
- fsFontUse
- Flags containing information about how the font is to be related to the character attributes:
- FATTR_FONTUSE_NOMIX
- Specifies that permissive mixing is allowed when the font is used. The engine can ignore any interaction with graphics primitives and can use overpaint and leave alone as the foreground and background mixes rather than using the current mix attributes.
- FATTR_FONTUSE_OUTLINE
- Specifies that the font must be an outline font. When the font is not defined by lMatch and FATTR_FONTUSE_OUTLINE is specified, the system searches for an outline font. If the search fails, a default font is selected. When the font is not defined by lMatch and FATTR_FONTUSE_OUTLINE is not set, the system searches for an image font that matches lMaxBaselineExt and lAveCharWidth. If this fails, it searches for an outline font with the required szFaceName and fsSelection flags.
- FATTR_FONTUSE_TRANSFORMABLE
- Specifies that the font must be transformable (that is, it can be scaled, rotated, and sheared). Transformable fonts are used only in CM_MODE3. Nontransformable fonts can be used in CM_MODE1 or CM_MODE2 but not in CM_MODE3.
- pInstance (PVOID) - input
- Pointer to instance data.
- lFunction (ULONG) - input
- High-order WORD=flags; low-order WORD=NGreCreateLogicalFont.
Returns
- rc (LONG) - returns
- Return Codes.
- This function returns a LONG value indicating whether the font has been matched:
- FONT_DEFAULT The font was not matched. The default font is to be used.
- FONT_MATCH The font has been matched successfully.
- GPI_ERROR Error.
- Possible Errors Detected
- When an error is detected, the graphics engine calls WinSetErrorInfo to post the condition. Reasons for failure of this function include:
- PMERR_BASE_ERROR
- 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_EXTENDED_LCID
- PMERR_INV_FONT_ATTRS
- PMERR_INV_FONTDEF
- PMERR_INV_HDC
- PMERR_INV_IN_AREA
- PMERR_INV_LENGTH_OR_COUNT
- PMERR_INV_SETID
- PMERR_SETID_IN_USE
- Refer to the "Error Explanations" section of the Presentation Manager Programming Reference for further explanation.
Sample
#define INCL_GRE_FONTS #include <os2.h> HDC hdc; /* Device context handle. */ LONG lcid; /* Local identifier that is to be assigned to the font. */ PSTR8 pchName; /* Pointer. */ PFATTRS pAttrs; /* Pointer. */ PVOID pInstance; /* Pointer to instance data. */ ULONG lFunction; /* High-order WORD=flags; low-order WORD=NGreCreateLogicalFont. */ LONG rc; /* Return Codes. */ rc = GreCreateLogicalFont(hdc, lcid, pchName, pAttrs, pInstance, lFunction);
Remarks
The parameters passed to the function identify the name and attributes of the required font. The graphics engine selects a font from the list of available fonts that provides the best match for the font attributes addressed by pAttrs.
The selection is made in one of two ways:
- If the lMatch attribute is nonzero, the calling program has already determined (from a call to GreQueryFonts) which font it requires. In this case, the graphics engine selects the font identified by the lMatch and szFaceName attributes (or, if szFaceName is not specified, lMatch alone).
- If lMatch is 0 or a suitable match could not be found, the system examines the other fields in the attributes structure and selects the font that gives the best match.
If no match is found, the default font is used. When assigned, the system will not change the relationship of a specific lcid to a specific font.
The interaction between fonts and character attributes depends on the state of the FATTRS_FONTUSE_TRANSFORMABLE flag in the font attributes structure. When this flag is set:
- The size of the characters is determined by the values of the character attributes at the time that the characters are drawn.
- The characters are positioned, rotated, and sheared, as required.
- No checking is done.
- Any transformation is performed by mapping the box defined by the FONTMETRICS parameters, xMaxCharInc and yEmHeight, to the character box under the influence of character angle and shear.
When the FATTRS_FONTUSE_TRANSFORMABLE flag is not set, the lAveCharWidth and lBaselineExt parameters in the font attributes structure define the size of the font to be used. The character box attribute has no effect.
Transformable fonts cannot be used in Character Modes 1 and 2. Nontransformable fonts cannot be used in Character Mode 3. If the font is not compatible with the character mode, the engine raises an error when the presentation driver attempts to draw characters. The characteristics of the character modes are:
- CM_MODE1
- The position of characters after the first character is determined by the font metrics information. Character box, angle, shear, extra, break extra, and spacing are ignored.
- CM_MODE2
- The position of characters is determined by the font metrics information and the character attributes. Characters are not scaled, rotated, or sheared.
- CM_MODE3
- The position of characters is determined by the font metrics information and all character attributes. Characters can be scaled, rotated, and sheared.
Positioning is performed by using the character reference point defined within the font. When characters that are not hollow are drawn using an outline font, they are filled using the character foreground color and mix.