API Reference Win32 Functions

CreateFont

HFONT CreateFont( [in] int cHeight, [in] int cWidth, [in] int cEscapement, [in] int cOrientation, [in] int cWeight, [in] DWORD fdwWeight, [in] DWORD fdwItalic, [in] DWORD fdwUnderline, [in] DWORD fdwStrikeOut, [in] DWORD fdwCharSet, [in] DWORD fdwOutputPrecision, [in] DWORD fdwQuality, [in] DWORD fdwPitchAndFamily, [in] LPCTSTR lpszFace );

Description

The CreateFont function creates a logical font with the specified characteristics. The font object can then be selected into a device context by calling the SelectObject function.

The parameters specify the desired characteristics of the font. The system uses these values to find the closest match in the available physical fonts.

Parameters

cHeight
The desired height of the font in logical units. The height can be in two forms:
  • Positive value: The height of the font in logical units.
  • Negative value: The average character width in logical units.
For a detailed explanation, see the Remarks section.
cWidth
The desired width of the font in logical units. The width can be in two forms:
  • Positive value: The width of the font in logical units.
  • Negative value: The average character width in logical units.
For a detailed explanation, see the Remarks section.
cEscapement
The escapement of the font in tenths of a degree. The escapement is the angle, measured in tenths of a degree, between the escapement vector and the horizontal x-axis. The escapement vector determines the direction in which characters are placed on a line. For example, a horizontal argument of 0 means that characters are drawn horizontally, and an argument of 900 means that characters are drawn vertically. This value is typically used for TrueType fonts. The orientation of the string is also affected by the cOrientation parameter.
cOrientation
The orientation of the string of characters in the font in tenths of a degree. The orientation is the angle, measured in tenths of a degree, between the string's base line and the x-axis. This value is typically used for TrueType fonts.
cWeight
The desired font weight. This parameter can be one of the following predefined values:
  • FW_DONTCARE (0)
  • FW_THIN (100)
  • FW_EXTRALIGHT (200)
  • FW_LIGHT (300)
  • FW_NORMAL (400)
  • FW_MEDIUM (500)
  • FW_SEMIBOLD (600)
  • FW_BOLD (700)
  • FW_EXTRABOLD (800)
  • FW_HEAVY (900)
Or it can be a value from 1 to 1000, in increments of 1.
fdwItalic
Specifies the height of the font in logical units. The height can be in two forms:
  • Set this bit to TRUE for italic text.
  • Set this bit to FALSE for non-italic text.
fdwUnderline
Specifies whether the font is underlined.
  • Set this bit to TRUE for underlined text.
  • Set this bit to FALSE for non-underlined text.
fdwStrikeOut
Specifies whether the font is struck out.
  • Set this bit to TRUE for strikeout text.
  • Set this bit to FALSE for non-strikeout text.
fdwCharSet
Specifies the character set. This parameter can be one of the following values:
  • ANSI_CHARSET
  • DEFAULT_CHARSET
  • EASTASIAN_CHARSET
  • GB2312_CHARSET
  • IDENTITY_CHARSET
  • SHIFTJIS_CHARSET
  • SYMBOL_CHARSET
  • UNICODE_CHARSET
fdwOutputPrecision
Specifies the desired output precision. The output precision determines how closely the physical font will match the logical font request. This parameter can be one or more of the following values:
  • OUT_DEFAULT_PRECIS
  • OUT_STRING_PRECIS
  • OUT_ONLY_PRECIS
  • OUT_OUTLINE_PRECIS
  • OUT_RASTER_PRECIS
  • OUT_STROKE_PRECIS
  • OUT_TT_ONLY_PRECIS
  • OUT_TT_COMPSUBSTRING_PRECIS
fdwQuality
Specifies the desired font quality. The font quality determines how the graphics device interface (GDI) determines if there is a physical font matching the given string. This parameter can be one of the following values:
  • DEFAULT_QUALITY
  • DRAFT_QUALITY
  • PROOF_QUALITY
  • NONANTIALIASED_QUALITY
  • CLEARTYPE_QUALITY
  • ANTIALIASED_QUALITY
fdwPitchAndFamily
Specifies the pitch and font family. This parameter can be a combination of a pitch value and a family value. Pitch values:
  • DEFAULT_PITCH
  • FIXED_PITCH
  • VARIABLE_PITCH
Font families:
  • FF_DONTCARE
  • FF_ROMAN
  • FF_SWISS
  • FF_MODERN
  • FF_SCRIPT
  • FF_DECORATIVE
lpszFace
A pointer to a null-terminated string that specifies the name of the typeface. The string can be any of the TrueType font names available on the system.

Return Value

If the function succeeds, the return value is a handle to the newly created logical font object. A font handle is a value that uniquely identifies a font.

If the function fails, the return value is NULL.

Remarks

The GDI maps the font characteristics specified by the CreateFont parameters to the closest available font in the system. If an exact match is not found, the GDI substitutes font characteristics as necessary.

Character Height

The interpretation of the cHeight parameter depends on the coordinate system of the device context.

The font height is measured from the baseline of the characters.

Character Width

The cWidth parameter specifies the average width of characters in the font. For most fonts, this value is the width of the character 'X'. If cWidth is 0, the GDI selects the closest matching character width for the font.

Escapement and Orientation

The cEscapement and cOrientation parameters control the orientation of characters within a font.

For TrueType fonts, the cEscapement and cOrientation values are often the same, resulting in characters being drawn with the specified rotation.

Font Families

The fdwPitchAndFamily parameter specifies the pitch (e.g., fixed or variable) and the font family (e.g., Roman, Swiss, Modern). The GDI uses this information to select a font from the specified family that best matches the other font characteristics. If FF_DONTCARE is specified, the GDI can choose any font family.

Font Quality

The fdwQuality parameter influences how the GDI selects a font.

Example Usage


// Create a bold, italic, underlined font
LOGFONT lf = {0};
lf.lfHeight = -15; // Font height in logical units
lf.lfWeight = FW_BOLD; // Font weight
lf.lfItalic = TRUE; // Italic
lf.lfUnderline = TRUE; // Underlined
lf.lfCharSet = DEFAULT_CHARSET; // Character set
lf.lfOutPrecision = OUT_DEFAULT_PRECIS; // Output precision
lf.lfQuality = DEFAULT_QUALITY; // Font quality
lf.lfPitchAndFamily = DEFAULT_PITCH | FF_SWISS; // Pitch and family

// Copy the face name
wcscpy_s(lf.lfFaceName, LF_FACESIZE, L"Arial");

HFONT hFont = CreateFontIndirect(&lf);

if (hFont != NULL) {
    // Select the font into the device context
    HDC hdc = GetDC(NULL); // Get screen DC for example
    HGDIOBJ hOldFont = SelectObject(hdc, hFont);

    // Use the font...

    // Clean up
    SelectObject(hdc, hOldFont);
    DeleteObject(hFont);
    ReleaseDC(NULL, hdc);
}

See Also