CFont Class

Encapsulates a Windows graphics device interface (GDI) font and provides member functions for manipulating the font.

Syntax

class CFont : public CGdiObject

Members

Public Constructors

Public Methods

Public Operators

Remarks

To use a CFont object, construct a CFont object and attach a Windows font to it with CreateFont, CreateFontIndirect, CreatePointFont, or CreatePointFontIndirect, and then use the object's member functions to manipulate the font.

The CreatePointFont and CreatePointFontIndirect functions are often easier to use than CreateFont or CreateFontIndirect since they do the conversion for the height of the font from a point size to logical units automatically.

For more information on CFont, see Graphic Objects.

Inheritance Hierarchy

CObject

CGdiObject

CFont

Requirements

Header: afxwin.h

CFont::CFont

Constructs a CFont object.

CFont();

Remarks

The resulting object must be initialized with CreateFont, CreateFontIndirect, CreatePointFont, or CreatePointFontIndirect before it can be used.

Example

CFont font;

CFont::CreateFont

Initializes a CFont object with the specified characteristics.

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,
    LPCTSTR lpszFacename);

Parameters

nHeight
Specifies the desired height (in logical units) of the font. See the lfHeight member of the LOGFONTstructure in the Windows SDK for a description. The absolute value of nHeight must not exceed 16,384 device units after it is converted. For all height comparisons, the font mapper looks for the largest font that does not exceed the requested size or the smallest font if all the fonts exceed the requested size.

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. See the lfEscapement member in the LOGFONT structure in the Windows SDK for more information.

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 for coordinate systems in which the y-direction is down and clockwise from the x-axis for coordinate systems in which the y-direction is up.

nWeight
Specifies the font weight (in inked pixels per 1000). See the lfWeight member in the LOGFONT structure in the Windows SDK for more information. The described values are approximate; the actual appearance 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.

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 setSee the lfCharSet member in the LOGFONT structure in the Windows SDK for a list of values.

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.

The font mapper does not use the DEFAULT_CHARSET value. An application can use this value to allow the name and size of a font to fully describe the logical font. If a font with the specified 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.

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. See the lfOutPrecision member in the LOGFONT structure in the Windows SDK for a list of values and more information.

nClipPrecision
Specifies the desired clipping precision. The clipping precision defines how to clip characters that are partially outside the clipping region. See the lfClipPrecision member in the LOGFONT structure in the Windows SDK for a list of values.

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

To achieve consistent rotation of device, TrueType, and vector fonts, an application can use the bitwise OR operator (|) to combine the CLIP_LH_ANGLES value with any of the other nClipPrecision values. If the CLIP_LH_ANGLES bit is set, the rotation for all fonts depends on whether the orientation of the coordinate system is left-handed or right-handed. (For more information about the orientation of coordinate systems, see the description of the nOrientation parameter.) 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.

nQuality
Specifies the font's output quality, which defines how carefully the GDI must attempt to match the logical-font attributes to those of an actual physical font. See the lfQuality member in the LOGFONT structure in the Windows SDK for a list of values.

nPitchAndFamily
Specifies the pitch and family of the font. See the lfPitchAndFamily member in the LOGFONT structure in the Windows SDK for a list of values and more information.

lpszFacename
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 EnumFontFamilies function can be used to enumerate all currently available fonts. If lpszFacename is NULL, the GDI uses a device-independent typeface.

Return Value

Nonzero if successful; otherwise 0.

Remarks

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 physical fonts available to the GDI.

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

When you finish with the CFont object created by the CreateFont function, use CDC::SelectObject to select a different font into the device context, then delete the CFont object that is no longer needed.

Example

// The code fragment shows how to create a font object,
// select the font object into a DC (device context) for text
// drawing, and finally delete the font object.

// Initializes a CFont object with the specified characteristics.
CFont font;
VERIFY(font.CreateFont(
    12,                       // nHeight
    0,                        // nWidth
    0,                        // nEscapement
    0,                        // nOrientation
    FW_NORMAL,                // nWeight
    FALSE,                    // bItalic
    FALSE,                    // bUnderline
    0,                        // cStrikeOut
    ANSI_CHARSET,             // nCharSet
    OUT_DEFAULT_PRECIS,       // nOutPrecision
    CLIP_DEFAULT_PRECIS,      // nClipPrecision
    DEFAULT_QUALITY,          // nQuality
    DEFAULT_PITCH | FF_SWISS, // nPitchAndFamily
    _T("Arial")));            // lpszFacename

// Do something with the font just created...
CClientDC dc(this);
CFont *def_font = dc.SelectObject(&font);
dc.TextOut(5, 5, _T("Hello"), 5);
dc.SelectObject(def_font);

// Done with the font.  Delete the font object.
font.DeleteObject();

CFont::CreateFontIndirect

Initializes a CFont object with the characteristics given in a LOGFONTstructure.

BOOL CreateFontIndirect(const LOGFONT* lpLogFont);

Parameters

lpLogFont
Points to a LOGFONT structure that defines the characteristics of the logical font.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The font can subsequently be selected as the current font for any device.

This font has the characteristics specified in the LOGFONT structure. When the font is selected by using the CDC::SelectObject member function, the GDI font mapper attempts to match the logical font with an existing physical font. If the font mapper fails to find an exact match for the logical font, it provides an alternative font whose characteristics match as many of the requested characteristics as possible.

When you no longer need the CFont object created by the CreateFontIndirect function, use CDC::SelectObject to select a different font into the device context, then delete the CFont object that is no longer needed.

Example

// The code fragment shows how to create a font object,
// select the font object into a DC (device context) for text
// drawing, and finally delete the font object.

// Initializes a CFont object with the characteristics given
// in a LOGFONT structure.
CFont font;
LOGFONT lf;
memset(&lf, 0, sizeof(LOGFONT)); // zero out structure
lf.lfHeight = 12;                // request a 12-pixel-height font
_tcsncpy_s(lf.lfFaceName, LF_FACESIZE,
           _T("Arial"), 7);           // request a face name "Arial"
VERIFY(font.CreateFontIndirect(&lf)); // create the font

// Do something with the font just created...
CClientDC dc(this);
CFont *def_font = dc.SelectObject(&font);
dc.TextOut(5, 5, _T("Hello"), 5);
dc.SelectObject(def_font);

// Done with the font. Delete the font object.
font.DeleteObject();

CFont::CreatePointFont

This function provides a simple way to create a font of a specified typeface and point size.

BOOL CreatePointFont(
    int nPointSize,
    LPCTSTR lpszFaceName,
    CDC* pDC = NULL);

Parameters

nPointSize
Requested font height in tenths of a point. (For instance, pass 120 to request a 12-point font.)

lpszFaceName
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 EnumFontFamilies function can be used to enumerate all currently available fonts. If lpszFaceName is NULL, the GDI uses a device-independent typeface.

pDC
Pointer to the CDC object to be used to convert the height in nPointSize to logical units. If NULL, a screen device context is used for the conversion.

Return Value

Nonzero if successful, otherwise 0.

Remarks

It automatically converts the height in nPointSize to logical units using the CDC object pointed to by pDC.

When you finish with the CFont object created by the CreatePointFont function, first select the font out of the device context, then delete the CFont object.

Example

// The code fragment shows how to create a font object,
// select the font object into a DC (device context) for text
// drawing, and finally delete the font object.

CClientDC dc(this);

CFont font;
VERIFY(font.CreatePointFont(120, _T("Arial"), &dc));

// Do something with the font just created...
CFont *def_font = dc.SelectObject(&font);
dc.TextOut(5, 5, _T("Hello"), 5);
dc.SelectObject(def_font);

// Done with the font. Delete the font object.
font.DeleteObject();

CFont::CreatePointFontIndirect

This function is the same as CreateFontIndirect except that the lfHeight member of the LOGFONT is interpreted in tenths of a point rather than device units.

BOOL CreatePointFontIndirect(
    const LOGFONT* lpLogFont,
    CDC* pDC = NULL);

Parameters

lpLogFont
Points to a LOGFONT structure that defines the characteristics of the logical font. The lfHeight member of the LOGFONT structure is measured in tenths of a point rather than logical units. (For instance, set lfHeight to 120 to request a 12-point font.)

pDC
Pointer to the CDC object to be used to convert the height in lfHeight to logical units. If NULL, a screen device context is used for the conversion.

Return Value

Nonzero if successful, otherwise 0.

Remarks

This function automatically converts the height in lfHeight to logical units using the CDC object pointed to by pDC before passing the LOGFONT structure on to Windows.

When you finish with the CFont object created by the CreatePointFontIndirect function, first select the font out of the device context, then delete the CFont object.

Example

// The code fragment shows how to create a font object,
// select the font object into a DC (device context) for text
// drawing, and finally delete the font object.
LOGFONT lf;

// clear out structure.
memset(&lf, 0, sizeof(LOGFONT));

// request a 12-pixel-height font
lf.lfHeight = 120;

// request a face name "Arial".
_tcsncpy_s(lf.lfFaceName, LF_FACESIZE, _T("Arial"), 7);

CClientDC dc(this);

CFont font;
VERIFY(font.CreatePointFontIndirect(&lf, &dc));

// Do something with the font just created...
CFont *def_font = dc.SelectObject(&font);
dc.TextOut(5, 5, _T("Hello"), 5);
dc.SelectObject(def_font);

// Done with the font. Delete the font object.
font.DeleteObject();

CFont::FromHandle

Returns a pointer to a CFont object when given an HFONT handle to a Windows GDI font object.

static CFont* PASCAL FromHandle(HFONT hFont);

Parameters

hFont
An HFONT handle to a Windows font.

Return Value

A pointer to a CFont object if successful; otherwise NULL.

Remarks

If a CFont object is not already attached to the handle, a temporary CFont object is created and attached. This temporary CFont object is valid only until the next time the application has idle time in its event loop, at which time all temporary graphic objects are deleted. Another way of saying this is that the temporary object is valid only during the processing of one window message.

Example

// The code fragment shows how to create a font object using
// Windows API CreateFontIndirect(), convert the HFONT to a
// CFont* before selecting the font object into a DC (device
// context) for text drawing, and finally delete the font object.

// Initialize a CFont object with the characteristics given
// in a LOGFONT structure.
LOGFONT lf;

// clear out structure
memset(&lf, 0, sizeof(LOGFONT));
// request a 12-pixel-height font
lf.lfHeight = 12;
// request a face name "Arial"
_tcsncpy_s(lf.lfFaceName, LF_FACESIZE, _T("Arial"), 7);
// create the font
HFONT hfont = ::CreateFontIndirect(&lf);

// Convert the HFONT to CFont*.
CFont *pfont = CFont::FromHandle(hfont);

// Do something with the font just created...
CClientDC dc(this);
CFont *def_font = dc.SelectObject(pfont);
dc.TextOut(5, 5, _T("Hello"), 5);
dc.SelectObject(def_font);

// Done with the font. Delete the font object.
::DeleteObject(hfont);

CFont::GetLogFont

Call this function to retrieve a copy of the LOGFONT structure for CFont.

int GetLogFont(LOGFONT* pLogFont);

Parameters

pLogFont
Pointer to the LOGFONT structure to receive the font information.

Return Value

Nonzero if the function succeeds, otherwise 0.

Example

// The code fragment shows how to retrieve a copy of the
// LOGFONT structure for a currently selected font of a window.

CFont *pFont = pWnd->GetFont();
if (NULL != pFont)
{
   LOGFONT lf;
   pFont->GetLogFont(&lf);
   TRACE(_T("Typeface name of font = %s\n"), lf.lfFaceName);
}

CFont::operator HFONT

Use this operator to get the Windows GDI handle of the font attached to the CFont object.

operator HFONT() const;

Return Value

The handle of the Windows GDI font object attached to CFont if successful; otherwise NULL.

Remarks

Since this operator is automatically used for conversions from CFont to Fonts and Text, you can pass CFont objects to functions that expect HFONTs.

For more information about using graphic objects, see Graphic Objects in the Windows SDK.

Example

// The code fragment shows the usage of CFont::operator HFONT.

// Initialize a CFont object with the characteristics given
// in a LOGFONT structure.
LOGFONT lf;

// clear out structure
memset(&lf, 0, sizeof(LOGFONT));

// request a 12-pixel-height font
lf.lfHeight = 12;

// request a face name "Arial"
_tcsncpy_s(lf.lfFaceName, LF_FACESIZE, _T("Arial"), 7);

CFont font1;
font1.CreateFontIndirect(&lf); // create the font

// CFont::operator HFONT automatically converts font1 from
// CFont* to HFONT.
CFont *font2 = CFont::FromHandle(font1);

// Do something with the font just created...
CClientDC dc(this);
CFont *def_font = dc.SelectObject(font2);
dc.TextOut(5, 5, _T("Hello"), 5);
dc.SelectObject(def_font);

// Done with the font. Delete the font object.
font1.DeleteObject();

See also

MFC Sample HIERSVR
CGdiObject Class
Hierarchy Chart