CreateFont

2.x

The CreateFont function creates a logical font that has the specified characteristics. The logical font can subsequently be selected as the font for any device.

Parameters

nHeight

Specifies the requested height, in logical units, for the font. If this parameter is greater than zero, it specifies the cell height of the font. If it is less than zero, it specifies the character height of the font. (Character height is the cell height minus the internal leading. Applications that specify font height in points typically use a negative number for this member.) If this parameter is zero, the font mapper uses a default height. The font mapper chooses the largest physical font that does not exceed the requested size (or the smallest font, if all the fonts exceed the requested size). The absolute value of the nHeight parameter must not exceed 16,384 after it is converted to device units.

nWidth

Specifies the average width, in logical units, of characters in the font. If this parameter is zero, the font mapper chooses a “closest match” default width for the specified font height. (The default width is chosen by matching the aspect ratio of the device against the digitization aspect ratio of the available fonts. The closest match is determined by the absolute value of the difference.)

nEscapement

Specifies the angle, in tenths of degrees, between the escapement vector and the x-axis of the screen surface. The escapement vector is the line through the origins of the first and last characters on a line. The angle is measured counterclockwise from the x-axis.

nOrientation

Specifies the angle, in tenths of degrees, between the base line of a character and the x-axis. The angle is measured in a counterclockwise direction from the x-axis for left-handed coordinate systems (that is, MM_TEXT, in which the y-direction is down) and in a clockwise direction from the x-axis for right-handed coordinate systems (in which the y-direction is up).

fnWeight

Specifies the font weight. This parameter can be one of the following values:

The appearance of the font depends on the typeface. Some fonts have only FW_NORMAL, FW_REGULAR, and FW_BOLD weights. If FW_DONTCARE is specified, a default weight is used.

fbItalic

Specifies an italic font if set to nonzero.

fbUnderline

Specifies an underlined font if set to nonzero.

fbStrikeOut

Specifies a strikeout font if set to nonzero.

fbCharSet

Specifies the character set of the font. The following values are predefined:

The DEFAULT_CHARSET value is not used by the font mapper. An application can use this value to allow the name and size of a font to fully describe the logical font. If the specified font name does not exist, a font from any character set can be substituted for the specified font; to avoid unexpected results, applications should use the DEFAULT_CHARSET value sparingly.

The OEM character set is system-dependent.

Fonts with other character sets may exist in the system. If an application uses a font with an unknown character set, it should not attempt to translate or interpret strings that are to be rendered with that font.

fbOutputPrecision

Specifies the requested output precision. The output precision defines how closely the output must match the requested font's height, width, character orientation, escapement, and pitch. This parameter can be one of the following values:

OUT_CHARACTER_PRECIS OUT_DEFAULT_PRECIS OUT_DEVICE_PRECIS OUT_RASTER_PRECIS OUT_STRING_PRECIS OUT_STROKE_PRECIS OUT_TT_PRECIS

Applications can use the OUT_DEVICE_PRECIS, OUT_RASTER_PRECIS, and OUT_TT_PRECIS values to control how the font mapper chooses a font when the system contains more than one font with a given name. For example, if a system contained a font named Symbol in raster and TrueType form, specifying OUT_TT_PRECIS would force the font mapper to choose the TrueType version. (Specifying OUT_TT_PRECIS forces the font mapper to choose a TrueType font whenever the specified font name matches a device or raster font, even when there is no TrueType font of the same name.)

fbClipPrecision

Specifies the requested clipping precision. The clipping precision defines how to clip characters that are partially outside the clipping region. This parameter can be one of the following values:

CLIP_CHARACTER_PRECIS CLIP_DEFAULT_PRECIS CLIP_ENCAPSULATE CLIP_LH_ANGLES CLIP_MASK CLIP_STROKE_PRECIS CLIP_TT_ALWAYS

To use an embedded read-only font, applications must specify CLIP_ENCAPSULATE.

To achieve consistent rotation of device, TrueType, and vector fonts, an application can use the OR operator to combine the CLIP_LH_ANGLES value with any of the other fbClipPrecision values. If the CLIP_LH_ANGLES bit is set, the rotation for all fonts is dependent on whether the orientation of the coordinate system is left-handed or right-handed. If CLIP_LH_ANGLES is not set, device fonts always rotate counterclockwise, but the rotation of other fonts is dependent on the orientation of the coordinate system. (For more information about the orientation of coordinate systems, see the description of the nOrientation parameter.)

fbQuality

Specifies the output quality of the font, which defines how carefully the graphics device interface (GDI) must attempt to match the attributes of a logical font to those of a physical font. This parameter can be one of the following values:

fbPitchAndFamily

Specifies the pitch and family of the font. The two low-order bits specify the pitch of the font and can be one of the following values:

DEFAULT_PITCH FIXED_PITCH VARIABLE_PITCH

Applications can set bit 2 (0x04) of the lfPitchAndFamily member to choose a TrueType font.

The four high-order bits specify the font family and can be one of the following values:

An application can specify a value for the fbPitchAndFamily parameter by using the Boolean OR operator to join a pitch constant with a family constant.

Font families describe the look of a font in a general way. They are intended for specifying fonts when the exact typeface requested is not available.

lpszFace

Points to a null-terminated string that specifies the typeface name of the font. The length of this string must not exceed LF_FACESIZE – 1. The EnumFontFamilies function can be used to enumerate the typeface names of all currently available fonts. If this parameter is NULL, GDI uses a device-dependent typeface.

Return Value

The return value is the handle of the logical font if the function is successful. Otherwise, it is NULL.

Comments

The CreateFont function creates the handle of a logical font. The font mapper uses this logical font to find the closest match from the fonts available in GDI's pool of physical fonts.

Applications can use the default settings for most of these parameters when creating a logical font. The parameters that should always be given specific values are nHeight and lpszFace. If nHeight and lpszFace are not set by the application, the logical font that is created is device-dependent.

Fonts created by using the CreateFont function must be selected out of any device context in which they were used and then removed by using the DeleteObject function.

Example

The following example sets the mapping mode to MM_TWIPS and then uses the CreateFont function to create an 18-point logical font:

HFONT hfont, hfontOld;
int MapModePrevious, iPtSize = 18;
PSTR pszFace = "MS Serif";

MapModePrevious = SetMapMode(hdc, MM_TWIPS);
hfont = CreateFont(-iPtSize * 20, 0, 0, 0, 0, /* specify pt size    */
    0, 0, 0, 0, 0, 0, 0, 0, pszFace);         /* and face name only */

hfontOld = SelectObject(hdc, hfont);

TextOut(hdc, 100, -500, pszFace, strlen(pszFace));
SetMapMode(hdc, MapModePrevious);
SelectObject(hdc, hfontOld);
DeleteObject(hfont);

See Also

CreateFontIndirect, DeleteObject, EnumFontFamilies