EnumFontFamiliesExA 函式 (wingdi.h)

發行項
03/04/2024

EnumFontFamiliesEx 函式會列舉系統中所有唯一命名的字型，這些字型符合 LOGFONT 結構所指定的字型特性。 EnumFontFamiliesEx 會根據字樣名稱、字元集或兩者列舉字型。

語法

int EnumFontFamiliesExA(
  [in] HDC           hdc,
  [in] LPLOGFONTA    lpLogfont,
  [in] FONTENUMPROCA lpProc,
  [in] LPARAM        lParam,
       DWORD         dwFlags
);

參數

[in] hdc

要從中列舉字型之裝置內容的句柄。

[in] lpLogfont

LOGFONT 結構的指標，其中包含要列舉之字型的相關信息。函式會檢查下列成員。

member	描述
lfCharSet	如果設定為 DEFAULT_CHARSET，函式會列舉所有字元集中唯一命名的字型。 (如果有兩個字型具有相同的名稱，則只會列舉一個。) 如果設定為有效的字元集值，函式只會列舉指定字元集中的字型。
lfFaceName	如果設定為空字串，函式會列舉每個可用字樣名稱中的一個字型。如果設定為有效的字樣名稱，函式會列舉具有指定名稱的所有字型。
lfPitchAndFamily	操作系統的所有語言版本都必須設定為零。

[in] lpProc

應用程式定義回呼函式的指標。如需詳細資訊，請參閱 EnumFontFamExProc 函式。

[in] lParam

應用程式定義值。函式會將此值連同字型資訊傳遞至回調函式。

dwFlags

這個參數不會使用，而且必須是零。

傳回值

傳回值是回呼函式所傳回的最後一個值。此值取決於指定裝置可用的字型系列。

備註

EnumFontFamiliesEx 函式不會使用標記的字樣名稱來識別字元集。相反地，它一律會將正確的字樣名稱和個別的字元集值傳遞給回調函式。函式會根據 LOGFONT 結構中的 lfCharSet 和 lfFaceName 成員值來列舉字型。

如同 EnumFontFamilies，EnumFontFamiliesEx 會列舉所有字型樣式。並非所有字型樣式都涵蓋相同的字元集。例如，Fontorama Bold 可能包含 ANSI、希臘文和斯拉夫字元，但 Fontorama Italic 可能只包含 ANSI 字元。因此，最好不要假設指定的字型涵蓋特定的字元集，即使它是 ANSI 字元集也一樣。下表顯示 lfCharSet 和 lfFaceName 的各種值組合結果。

值	意義
lfCharSet = DEFAULT_CHARSET lfFaceName = '\0'	列舉所有字元集內所有唯一命名的字型。如果有兩個字型具有相同的名稱，則只會列舉一個字型。
lfCharSet = DEFAULT_CHARSET lfFaceName = 特定字型	列舉特定字型中的所有字元集和樣式。
lfCharSet =特定字元集 lfFaceName = '\0'	列舉特定字元集中所有字型的所有樣式。
lfCharSet =特定字元集 lfFaceName = 特定字型	列舉特定字元集中字型的所有樣式。

下列程式代碼範例示範如何使用這些值。


// 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;

EnumFontFamilies 和 EnumFontFamiliesEx 的回呼函式非常類似。主要差異在於 ENUMLOGFONTEX 結構包含腳本欄位。

請注意，根據 lfCharSet 和 lfFaceName 的值， EnumFontFamiliesEx 會列舉與字型中不同字元集相同的字型。這可以建立大量字型清單，對使用者可能會造成負擔。例如，Century Schoolbook 字型可以針對西歐、希臘文、土耳其文和斯拉夫字元集顯示。若要避免這種情況，應用程式應該篩選字型清單。

許多東亞語言的字型有兩個字樣名稱：英文名稱和當地語系化名稱。 EnumFonts、 EnumFontFamilies 和 EnumFontFamiliesEx 如果系統地區設定不符合字型的語言，則會傳回英文字樣名稱。

當裝置內容上的圖形模式設定為 GM_ADVANCED使用 SetGraphicsMode 函式，並將 DEVICE_FONTTYPE 旗標傳遞至 FontType 參數時，此函式會傳回系統上的類型 1 和 OpenType 字型清單。當圖形模式未設定為GM_ADVANCED時，此函式會傳回系統上類型 1、OpenType 和 TrueType 字型的清單。

注意

wingdi.h 標頭會將 EnumFontFamiliesEx 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	wingdi.h (包含 Windows.h)
程式庫	Gdi32.lib
Dll	Gdi32.dll