CFont::CreateFont

Syntax

BOOL CreateFont( int nHeight, int nWidth, int nEscapement, int nOrientation, int nWeight, BYTE bItalic, BYTE bUnderline, BYTE cStrikeOut, BYTE nCharSet, BYTE nOutPrecision, BYTE nClipPrecision, BYTE nQuality, BYTE nPitchAndFamily, const char FAR* lpFacename );

Parameters

nHeight

Specifies the desired height (in logical units) of the font. The font height can be specified in three ways.

Height Result

Greater than 0 Height is transformed into device units and matched against the cell height of the available fonts.
Equal to 0 A reasonable default size is used.
Less than 0 Height is transformed into device units and the absolute value is matched against the character height of the available fonts.

For all height comparisons, the font mapper looks for the largest font that does not exceed the requested size. Then, if there is no such font, it looks for the smallest font available.

nWidth

Specifies the average width (in logical units) of characters in the font. If nWidth is 0, the aspect ratio of the device will be matched against the digitization aspect ratio of the available fonts to find the closest match, which is determined by the absolute value of the difference.

nEscapement

Specifies the angle (in 0.1-degree units) between the escapement vector and the x-axis of the display 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 0.1-degree units) between the baseline of a character and the x-axis. The angle is measured counterclockwise from the x-axis.

nWeight

Specifies the font weight (in inked pixels per 1000). Although nWeight can be any integer value from 0 to 1000, the common values are as follows:

Value Meaning

400 Normal
700 Bold

These values are approximate; the actual appearance depends on the typeface. If nWeight is 0, a default weight is used.

bItalic

Specifies whether the font is italic.

bUnderline

Specifies whether the font is underlined.

cStrikeOut

Specifies whether characters in the font are struck out. Specifies a strikeout font if set to a nonzero value.

nCharSet

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

ANSI_CHARSET OEM_CHARSET SYMBOL_CHARSET

The OEM character set is system-dependent.

Fonts with other character sets may exist in the system. An application that uses a font with an unknown character set must not attempt to translate or interpret strings that are to be rendered with that font. Instead, the strings should be passed directly to the output device driver.

nOutPrecision

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

OUT_CHARACTER_PRECIS OUT_DEFAULT_PRECIS OUT_STRING_PRECIS OUT_STROKE_PRECIS

nClipPrecision

Specifies the desired clipping precision. The clipping precision defines how to clip characters that are partially outside the clipping region. It can be any one of the following values:

CLIP_CHARACTER_PRECIS CLIP_DEFAULT_PRECIS CLIP_STROKE_PRECIS

nQuality

Specifies the font's output quality, which defines how carefully GDI must attempt to match the logical-font attributes to those of an actual physical font. It can be one of the following values:

Value Meaning

DEFAULT_QUALITY Appearance of the font does not matter.
DRAFT_QUALITY Appearance of the font is less important than when PROOF_QUALITY is used. For GDI raster fonts, scaling is enabled. Bold, italic, underline, and strikeout fonts are synthesized if necessary.
PROOF_QUALITY Character quality of the font is more important than exact matching of the logical-font attributes. For GDI raster fonts, scaling is disabled and the font closest in size is chosen. Bold, italic, underline, and strikeout fonts are synthesized if necessary.

nPitchAndFamily

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

DEFAULT_PITCH FIXED_PITCH VARIABLE_PITCH

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

Value Meaning

FF_DECORATIVE Novelty fonts. Old English, for example.
FF_DONTCARE Don't care or don't know.
FF_MODERN Fonts with constant stroke width (fixed-pitch), with or without serifs. Fixed-pitch fonts are usually modern. Pica, Elite, and Courier New are examples.
FF_ROMAN Fonts with variable stroke width (proportionally spaced) and with serifs. Times New Roman and Century Schoolbook are examples.
FF_SCRIPT Fonts designed to look like handwriting. Script and Cursive are examples.
FF_SWISS Fonts with variable stroke width (proportionally spaced) and without serifs. MS Sans Serif is an example.

An application can specify a value for nPitchAndFamily 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 desired is not available.

lpFacename

A CString or pointer to a null-terminated string that specifies the typeface name of the font. The length of this string must not exceed 30 characters. The Windows EnumFonts function can be used to enumerate all currently available fonts. If lpFacename is NULL, GDI uses a default typeface.

Remarks

Initializes a CFont object with the specified characteristics. The font can subsequently be selected as the font for any device context.

The CreateFont function does not create a new Windows GDI font. It merely selects the closest match from the fonts available in GDI's pool of physical fonts.

Return Value

TRUE if successful; otherwise FALSE.

See Also

CFont::CreateFontIndirect, ::CreateFont, ::EnumFonts