GreCreateLogicalFont

From EDM2
Jump to: navigation, search

GreCreateLogicalFont sets the local identifier (lcid) for a logical font.

This function is supported by the graphics engine.

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.