EnumFontFamiliesExA function (wingdi.h)
The EnumFontFamiliesEx function enumerates all uniquely-named fonts in the system that match the font characteristics specified by the LOGFONT structure. EnumFontFamiliesEx enumerates fonts based on typeface name, character set, or both.
Syntax
int EnumFontFamiliesExA(
[in] HDC hdc,
[in] LPLOGFONTA lpLogfont,
[in] FONTENUMPROCA lpProc,
[in] LPARAM lParam,
DWORD dwFlags
);
Parameters
[in] hdc
A handle to the device context from which to enumerate the fonts.
[in] lpLogfont
A pointer to a LOGFONT structure that contains information about the fonts to enumerate. The function examines the following members.
| Member | Description |
|---|---|
| lfCharSet | If set to DEFAULT_CHARSET, the function enumerates all uniquely-named fonts in all character sets. (If there are two fonts with the same name, only one is enumerated.) If set to a valid character set value, the function enumerates only fonts in the specified character set. |
| lfFaceName | If set to an empty string, the function enumerates one font in each available typeface name. If set to a valid typeface name, the function enumerates all fonts with the specified name. |
| lfPitchAndFamily | Must be set to zero for all language versions of the operating system. |
[in] lpProc
A pointer to the application defined callback function. For more information, see the EnumFontFamExProc function.
[in] lParam
An application defined value. The function passes this value to the callback function along with font information.
dwFlags
This parameter is not used and must be zero.
Return value
The return value is the last value returned by the callback function. This value depends on which font families are available for the specified device.
Remarks
The EnumFontFamiliesEx function does not use tagged typeface names to identify character sets. Instead, it always passes the correct typeface name and a separate character set value to the callback function. The function enumerates fonts based on the values of the lfCharSet and lfFaceName members in the LOGFONT structure.
As with EnumFontFamilies, EnumFontFamiliesEx enumerates all font styles. Not all styles of a font cover the same character sets. For example, Fontorama Bold might contain ANSI, Greek, and Cyrillic characters, but Fontorama Italic might contain only ANSI characters. For this reason, it's best not to assume that a specified font covers a specific character set, even if it is the ANSI character set. The following table shows the results of various combinations of values for lfCharSet and lfFaceName.
| Values | Meaning |
|---|---|
|
lfCharSet = DEFAULT_CHARSET
lfFaceName = '\0' |
Enumerates all uniquely-named fonts within all character sets. If there are two fonts with the same name, only one is enumerated. |
|
lfCharSet = DEFAULT_CHARSET
lfFaceName = a specific font |
Enumerates all character sets and styles in a specific font. |
|
lfCharSet =a specific character set
lfFaceName = '\0' |
Enumerates all styles of all fonts in the specific character set. |
|
lfCharSet =a specific character set
lfFaceName = a specific font |
Enumerates all styles of a font in a specific character set. |
The following code sample shows how these values are used.
// To enumerate all styles and charsets of all fonts:
lf.lfFaceName[0] = '\0';
lf.lfCharSet = DEFAULT_CHARSET;
HRESULT hr;
// To enumerate all styles and character sets of the Arial font:
hr = StringCchCopy( (LPSTR)lf.lfFaceName, LF_FACESIZE, "Arial" );
if (FAILED(hr))
{
// TODO: write error handler
}
lf.lfCharSet = DEFAULT_CHARSET;
// To enumerate all styles of all fonts for the ANSI character set
lf.lfFaceName[0] = '\0';
lf.lfCharSet = ANSI_CHARSET;
// To enumerate all styles of Arial font that cover the ANSI charset
hr = StringCchCopy( (LPSTR)lf.lfFaceName, LF_FACESIZE, "Arial" );
if (FAILED(hr))
{
// TODO: write error handler
}
lf.lfCharSet = ANSI_CHARSET;
The callback functions for EnumFontFamilies and EnumFontFamiliesEx are very similar. The main difference is that the ENUMLOGFONTEX structure includes a script field.
Note, based on the values of lfCharSet and lfFaceName, EnumFontFamiliesEx will enumerate the same font as many times as there are distinct character sets in the font. This can create an extensive list of fonts which can be burdensome to a user. For example, the Century Schoolbook font can appear for the Baltic, Western, Greek, Turkish, and Cyrillic character sets. To avoid this, an application should filter the list of fonts.
The fonts for many East Asian languages have two typeface names: an English name and a localized name. EnumFonts, EnumFontFamilies, and EnumFontFamiliesEx return the English typeface name if the system locale does not match the language of the font.
When the graphics mode on the device context is set to GM_ADVANCED using the SetGraphicsMode function and the DEVICE_FONTTYPE flag is passed to the FontType parameter, this function returns a list of type 1 and OpenType fonts on the system. When the graphics mode is not set to GM_ADVANCED, this function returns a list of type 1, OpenType, and TrueType fonts on the system.
Note
The wingdi.h header defines EnumFontFamiliesEx as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | wingdi.h (include Windows.h) |
| Library | Gdi32.lib |
| DLL | Gdi32.dll |