View source for GpiCreateLogFont

This function provides a logical definition of a font.

==Syntax==
 GpiCreateLogFont(hps, pName, lLcid, pfatAttrs)

==Parameters==
; hps ([[HPS]]) - input
: Presentation-space handle.

; pName ([[PSTR8]]) - input
: Logical font name.
: An 8-character name that can be used to describe the logical font. Its principal use is in interchange files, where it can help to identify the required font. If no interchange files are to be used, it can be null. For example, it can reference a file name that contains the font for a remote system.

; lLcid ([[LONG]]) - input
: Local identifier.
: The local identifier that the application uses to refer to this font. It must be in the range 0 through 254. If 0 is specified, the properties of the default font are changed. The original default font can be restored by calling [[GpiDeleteSetId]], with an lLcid parameter of LCID_DEFAULT or LCID_ALL.
: If the lLcid parameter specifies a local identifier that is already being used to refer to a logical font, but is not the current pattern-set or marker-set local identifier, then the new definition replaces the old one. If lLcid specifies a local identifier that is already being used to refer to a logical font, and is the current pattern-set or marker-set local identifier, an error occurs. An error also occurs if the local identifier is currently used to refer to a bit map.

; pfatAttrs ([[PFATTRS]]) - input
: Attributes required of the font.

==Return Value==
; lMatch ([[LONG]]) - returns
: Match indicators.
:; FONT_MATCH
:: Font requirements matched successfully.
:; FONT_DEFAULT
:: Font requirements not matched; a default font is used.
:; GPI_ERROR
:: Error occurred.

==Remarks==
The system uses the available physical font that most closely matches the requirements. Physical fonts can be:
* Loaded at initialization time
* Built into particular devices or device drivers
* Private ones for this process, loaded by [[GpiLoadFonts]].
An application can force selection of a particular physical font by quoting the lMatch value in FATTRS to be returned for the desired font by [[GpiQueryFonts]]. However, this method is only valid for a particular device/device driver combination on a single machine. This method should be avoided as a method for selecting fonts.
Whichever method is used, the choice of physical font, which is made when this function is issued, is never subsequently changed for a particular logical font.

The local identifier (lLcid) that the application decides to use to reference this logical font for later drawing operations is also specified; see [[GpiSetCharSet]].

If the face name is provided, GpiCreateLogFont tries to select the font with that face name. If the face name is empty, GpiCreateLogFont selects a default font.

When a match number is provided, GpiCreateLogFont tries to find a font with the same match number and face name. If there is a mismatch at this point, GpiCreateLogFont acts as though the match number is 0 and starts the search again.

When the match number is 0 and the calling program requests a bit-map font (FATTR_FONTUSE_OUTLINE not set), GpiCreateLogFont searches for a bit-map font with the required average character width (AveCharWidth) and maximum baseline extent (MaxBaselineExt), consistent with the usage flags. If this search fails, GpiCreateLogFont searches for an outline font with the required face name.

When the match number is zero and the calling program requests an outline font (FATTR_FONTUSE_OUTLINE is set), GpiCreateLogFont searches for an outline font with the required selection flags. If that search fails, a default outline font is selected. If the match number is set to a positive number, a Presentation Manager font is selected. If the match number is negative, a font belonging to a physical device is selected.
It is advisable to set the values of all the elements in the pfatAttrs structure. This is particularly important where printing, plotting, or interchange are concerned, as the target machine may need to substitute an existing device font for the requested font.

To anticipate possible substitution by a vector font, values should be set for character angle, character shear and character box (using [[GpiSetCharAngle]], [[GpiSetCharShear]], and [[GpiSetCharBox]] respectively) before drawing any character strings. The [[GpiQueryFontMetrics]] function can be used to get the values of the character box height and width for a font. These are held in the fields lEmHeight and lEmInc in the FONTMETRICS structure.

Outline font characters are normally drawn filled; however, hollow characters are produced if the FATTR_SEL_OUTLINE flag is set in the pfatAttrs parameter. For small characters, outlining in this way can give a similar visual appearance to filled characters, with improved performance.

There are restrictions on the use of non-installed fonts with certain device types. See [[GpiLoadFonts]] for more details.
If this function occurs within a path definition when the drawing mode (see [[GpiSetDrawingMode]]) is retain or draw-and-retain, its effect is not stored with the definition.

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; see "MetaFile Resolutions" in the Presentation Manager Programming Reference for more information.

==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_SETID (0x20CA)
: An invalid setid parameter was specified.
; PMERR_INV_FONT_ATTRS (0x2072)
: An invalid attrs parameter was specified with GpiCreateLogFont.
; PMERR_FONT_NOT_LOADED (0x202F)
: An attempt was made to create a font that was not loaded.
; PMERR_SETID_IN_USE (0x2102)
: An attempt was made to specify a setid that was already in use as the currently selected character, marker or pattern set.
; PMERR_KERNING_NOT_SUPPORTED (0x20D5)
: Kerning was requested on GpiCreateLogFont call to a presentation space associated with a device context that does not support kerning.

==Example Code==
<PRE>
#define INCL_GPILCIDS /* Or use INCL_GPI, INCL_PM, */
#include &lt;os2.h&gt;

HPS       hps;       /* Presentation-space handle. */
PSTR8     pName;     /* Logical font name. */
LONG      lLcid;     /* Local identifier. */
PFATTRS   pfatAttrs; /* Attributes required of the font. */
LONG      lMatch;    /* Match indicators. */

lMatch = GpiCreateLogFont(hps, pName, lLcid, pfatAttrs);
</PRE>

This example uses the GpiCreateLogFont function to create a logical font with the local identifier 1. The logical font has the face name "Courier" and requested width and height of 12 pels. Once the font is created, the example sets the font using the local identifier and displays a string in the font at the point (100,100).

<pre>
#define INCL_GPILCIDS /* Font functions */
#define INCL_GPIPRIMITIVES /* GPI primitive functions */
#include &lt;os2.h&gt;

HPS hps; /* presentation space handle */
POINTL ptl = { 100, 100 };
FATTRS fat;

fat.usRecordLength = sizeof(FATTRS); /* sets size of structure */
fat.fsSelection = 0; /* uses default selection */
fat.lMatch = 0L; /* does not force match */
fat.idRegistry = 0; /* uses default registry */
fat.usCodePage = 850; /* code-page 850 */
fat.lMaxBaselineExt = 12L; /* requested font height is 12 pels */
fat.lAveCharWidth = 12L; /* requested font width is 12 pels */
fat.fsType = 0; /* uses default type */
fat.fsFontUse = FATTR_FONTUSE_NOMIX;/* doesn't mix with graphics */

/* Copy Courier to szFacename field */
strcpy(fat.szFacename ,"Courier");

GpiCreateLogFont(hps, /* presentation space */
                 NULL, /* does not use logical font name */
                 1L, /* local identifier */
                 &fat); /* structure with font attributes */

GpiSetCharSet(hps, 1L); /* sets font for presentation space */
GpiCharStringAt(hps, &ptl, 5L, "Hello"); /* displays a string */
</pre>

==Related Functions==
* [[GpiDeleteSetId]]
* [[GpiLoadFonts]]
* [[GpiQueryFontMetrics]]
* [[GpiQueryFonts]]
* [[GpiQueryKerningPairs]]
* [[GpiQueryNumberSetIds]]
* [[GpiQuerySetIds]]
* [[GpiQueryWidthTable]]
* [[GpiSetCharMode]]
* [[GpiSetCharSet]]
* [[GpiSetMarkerSet]]
* [[GpiSetPatternSet]]
* [[GpiUnloadFonts]]

[[Category:Gpi]]