The CreateFont function creates a logical font that has specific characteristics. The logical font can subsequently be selected as the font for any device.
HFONT CreateFont(
|
int nHeight, |
// logical height of font |
|
int nWidth, |
// logical average character width |
|
int nEscapement, |
// angle of escapement |
|
int nOrientation, |
// base-line orientation angle |
|
int fnWeight, |
// font weight |
|
DWORD fdwItalic, |
// italic attribute flag |
|
DWORD fdwUnderline, |
// underline attribute flag |
|
DWORD fdwStrikeOut, |
// strikeout attribute flag |
|
DWORD fdwCharSet, |
// character set identifier |
|
DWORD fdwOutputPrecision, |
// output precision |
|
DWORD fdwClipPrecision, |
// clipping precision |
|
DWORD fdwQuality, |
// output quality |
|
DWORD fdwPitchAndFamily, |
// pitch and family |
|
LPCTSTR lpszFace |
// pointer to typeface name string |
|
); |
|
Value |
Meaning |
|
> 0 |
The font mapper transforms this value into device units and matches it against the cell height of the available fonts. |
|
0 |
The font mapper uses a default height value when it searches for a match. |
|
< 0 |
The font mapper transforms this value into device units and matches its absolute value 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.
This mapping occurs when the font is used for the first time.
For the MM_TEXT mapping mode, you can use the following formula to specify a height for a font with a specified point size:
nHeight = -MulDiv(PointSize, GetDeviceCaps(hDC, LOGPIXELSY), 72);
When the graphics mode is set to GM_COMPATIBLE, nEscapement specifies
both the escapement and orientation. You should set nEscapement and nOrientation
to the same value.
The following values are defined for convenience:
|
Value |
Weight |
|
FW_DONTCARE |
0 |
|
FW_THIN |
100 |
|
FW_EXTRALIGHT |
200 |
|
FW_ULTRALIGHT |
200 |
|
FW_LIGHT |
300 |
|
FW_NORMAL |
400 |
|
FW_REGULAR |
400 |
|
FW_MEDIUM |
500 |
|
FW_SEMIBOLD |
600 |
|
FW_DEMIBOLD |
600 |
|
FW_BOLD |
700 |
|
FW_EXTRABOLD |
800 |
|
FW_ULTRABOLD |
800 |
|
FW_HEAVY |
900 |
|
FW_BLACK |
900 |
ANSI_CHARSET
DEFAULT_CHARSET
SYMBOL_CHARSET
SHIFTJIS_CHARSET
GB2312_CHARSET
HANGEUL_CHARSET
CHINESEBIG5_CHARSET
OEM_CHARSET
The OEM_CHARSET value specifies a character set that is operating-system dependent.
You can use the DEFAULT_CHARSET 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, so you should use DEFAULT_CHARSET sparingly to avoid unexpected results.
Fonts with other character sets may exist in the operating system. If an application uses a font with an unknown character set, it should not attempt to translate or interpret strings that are rendered with that font.
This parameter is important in the font mapping process. To ensure consistent
results, specify a specific character set. If you specify a typeface name in
the lpszFace parameter, make sure that the fdwCharSet value
matches the character set of the typeface specified in lpszFace.
|
Value |
Meaning |
|
OUT_CHARACTER_PRECIS |
Not used. |
|
OUT_DEFAULT_PRECIS |
Specifies the default font mapper behavior. |
|
OUT_DEVICE_PRECIS |
Instructs the font mapper to choose a Device font when the system contains multiple fonts with the same name. |
|
OUT_OUTLINE_PRECIS |
Windows NT: This value instructs the font mapper to choose from TrueType and other outline-based fonts. Windows 95: This value is not used. |
|
OUT_RASTER_PRECIS |
Instructs the font mapper to choose a raster font when the system contains multiple fonts with the same name. |
|
OUT_STRING_PRECIS |
This value is not used by the font mapper, but it is returned when raster fonts are enumerated. |
|
OUT_STROKE_PRECIS |
Windows NT: This value is not used by the font mapper, but it is returned when TrueType, other outline-based fonts, and vector fonts are enumerated. Windows 95: This value is used to map vector fonts, and is returned when TrueType or vector fonts are enumerated. |
|
OUT_TT_ONLY_PRECIS |
Instructs the font mapper to choose from only TrueType fonts. If there are no TrueType fonts installed in the system, the font mapper returns to default behavior. |
|
OUT_TT_PRECIS |
Instructs the font mapper to choose a TrueType font when the system contains multiple fonts with the same name. |
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
operating system contains more than one font with a specified name. For
example, if an operating system contains a font named Symbol in raster and
TrueType form, specifying OUT_TT_PRECIS forces the font mapper to choose the
TrueType version. Specifying OUT_TT_ONLY_PRECIS forces the font mapper to
choose a TrueType font, even if it must substitute a TrueType font of another
name.
|
Value |
Meaning |
|
CLIP_DEFAULT_PRECIS |
Specifies default clipping behavior. |
|
CLIP_CHARACTER_PRECIS |
Not used. |
|
CLIP_STROKE_PRECIS |
Not used by the font mapper, but is returned when raster, vector, or TrueType fonts are enumerated. Windows NT: For compatibility, this value is always returned when enumerating fonts. |
|
CLIP_MASK |
Not used. |
|
CLIP_EMBEDDED |
You must specify this flag to use an embedded read-only font. |
|
CLIP_LH_ANGLES |
When this value is used, the rotation for all fonts depends on whether the orientation of the coordinate system is left-handed or right-handed. If not used, 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 |
|
CLIP_TT_ALWAYS |
Not used. |
|
Value |
Meaning |
|
DEFAULT_QUALITY |
Appearance of the font does not matter. |
|
DRAFT_QUALITY |
Appearance of the font is less important than when the PROOF_QUALITY value is used. For GDI raster fonts, scaling is enabled, which means that more font sizes are available, but the quality may be lower. 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. Although the chosen font size may not be mapped exactly when PROOF_QUALITY is used, the quality of the font is high and there is no distortion of appearance. Bold, italic, underline, and strikeout fonts are synthesized if necessary. |
DEFAULT_PITCH
FIXED_PITCH
VARIABLE_PITCH
The four high-order bits specify the font family and can be one of the following values:
|
Value |
Description |
|
FF_DECORATIVE |
Novelty fonts. Old English is an example. |
|
FF_DONTCARE |
Don’t care or don’t know. |
|
FF_MODERN |
Fonts with constant stroke width, with or without serifs. Pica, Elite, and Courier New® are examples. |
|
FF_ROMAN |
Fonts with variable stroke width and with serifs. MS® Serif is an example. |
|
FF_SCRIPT |
Fonts designed to look like handwriting. Script and Cursive are examples. |
|
FF_SWISS |
Fonts with variable stroke width and without serifs. MS Sans Serif is an example. |
An application can specify a value for the fdwPitchAndFamily 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.
If lpszFace is NULL or points to an empty string, GDI uses the first font that matches the other specified attributes.
If the function succeeds, the return value is a handle to a logical font.
If the function fails, the return value is NULL. To get extended error information, call GetLastError.
When you no longer need the font, call the DeleteObject function to delete it.
To help protect the copyrights of vendors who provide fonts for Windows operating systems, applications should always report the exact name of a selected font. Because available fonts can vary from system to system, do not assume that the selected font is always the same as the requested font. For example, if you request a font named “Palatino,” but no such font is available on the system, the font mapper will substitute a font that has similar attributes but a different name. Always report the name of the selected font to the user.