ExtTextOutA 函式 (wingdi.h)

發行項
03/13/2024

ExtTextOut 函式會使用目前選取的字型、背景色彩和文字色彩來繪製文字。您可以選擇性地提供要用於裁剪、不透明或兩者的維度。

語法

BOOL ExtTextOutA(
  [in] HDC        hdc,
  [in] int        x,
  [in] int        y,
  [in] UINT       options,
  [in] const RECT *lprect,
  [in] LPCSTR     lpString,
  [in] UINT       c,
  [in] const INT  *lpDx
);

參數

[in] hdc

裝置內容的句柄。

[in] x

用來放置字串之參考點的 x 座標，以邏輯座標表示。

[in] y

用來定位字串之參考點的 Y 座標，以邏輯座標表示。

[in] options

指定如何使用應用程式定義的矩形。此參數可以是下列一或多個值。

值	意義
ETO_CLIPPED	文字會裁剪到矩形。
ETO_GLYPH_INDEX	lpString 陣列是指從 GetCharacterPlacement 傳回的陣列，而且應該由 GDI 直接剖析，因為不需要進一步的語言特定處理。字元索引僅適用於 TrueType 字型，但旗標可用於點陣圖和向量字型，以指出不需要進一步的語言處理，GDI 應該直接處理字串。請注意，即使字串假設為點陣字型的8位值陣列，所有字元索引都是16位值。針對 ExtTextOutW，圖像索引會儲存至元檔。不過，若要顯示正確的字元，中繼文件必須使用相同的字型來播放。針對 ExtTextOutA，不會儲存字元索引。
ETO_IGNORELANGUAGE	保留供系統使用。如果應用程式設定此旗標，它就會失去國際腳本支援，在某些情況下，它完全不會顯示任何文字。
ETO_NUMERICSLATIN	若要顯示數位，請使用歐洲數位。
ETO_NUMERICSLOCAL	若要顯示數位，請使用適合地區設定的數位。
ETO_OPAQUE	目前的背景色彩應該用來填滿矩形。
ETO_PDY	設定這個值時， lpDx 所指向的陣列會包含一組值。每個配對的第一個值是連續字元儲存格的原點之間的距離，但第二個值是沿著字型垂直方向的位移。
ETO_RTLREADING	Windows 的中東語言版本：如果指定這個值，而且已選取希伯來文或阿拉伯文字型到裝置內容中，則字串會使用由右至左閱讀順序輸出。如果未指定此值，字串會以由左至右的順序輸出。在 SetTextAlign 中設定TA_RTLREADING值，即可達到相同的效果。此值會保留以供回溯相容性使用。

無法同時使用ETO_GLYPH_INDEX和ETO_RTLREADING值。由於ETO_GLYPH_INDEX表示所有語言處理都已完成，因此如果同時指定，函式會忽略ETO_RTLREADING旗標。

[in] lprect

選擇性 RECT 結構的指標，指定用於裁剪、不透明或兩者之矩形的邏輯座標維度。

[in] lpString

字串的指標，指定要繪製的文字。字串不需要以零結束，因為 cbCount 會指定字串的長度。

[in] c

lpString 所指向之字串的長度。

此值可能不會超過 8192。

[in] lpDx

值的選擇性陣列指標，指出相鄰字元儲存格之原點之間的距離。例如，lpDx[i] 邏輯儲存會分隔字元儲存格 i 和字元儲存格 i + 1 的來源。

傳回值

如果繪製字串，則傳回值為非零。不過，如果使用 ETO_GLYPH_INDEX呼叫 ExtTextOut 的 ANSI 版本，即使函式沒有執行任何動作，函式仍會傳回 TRUE 。

如果此函式失敗，則傳回值為零。

備註

指定裝置內容的目前文字對齊設定會決定參考點如何用來定位文字。呼叫 GetTextAlign 函式即可擷取文字對齊設定。藉由呼叫 SetTextAlign 函式來改變文字對齊設定。您可以使用下列值進行文字對齊。只有一個旗標可以從影響水準和垂直對齊的旗標中選擇。此外，只能選擇改變目前位置的兩個旗標之一。

詞彙	描述
TA_BASELINE	參考點會位於文字的底線上。
TA_BOTTOM	參考點會位於周框的下邊緣。
TA_TOP	參考點會位於周框的上邊緣。
TA_CENTER	參考點會水平對齊周框的中心。
TA_LEFT	參考點會位於周框的左邊緣。
TA_RIGHT	參考點會位於周框的右邊緣。
TA_NOUPDATECP	每次文字輸出呼叫之後，目前的位置都不會更新。參考點會傳遞至文字輸出函式。
TA_RTLREADING	Windows 的中東語言版本：文字會以從右至左閱讀順序配置，而不是預設的由左至右順序。只有在選取到裝置內容的字型為希伯來文或阿拉伯文時，才會適用。
TA_UPDATECP	每個文字輸出呼叫之後都會更新目前的位置。目前的位置會當做參考點使用。

如果 lpDx 參數為 NULL，ExtTextOut 函式會使用字元之間的預設間距。 lpDx 參數所指向之數位的字元儲存格原點和內容是以邏輯單元指定。字元儲存格原點定義為字元儲存格的左上角。

根據預設，此函式不會使用或更新目前的位置。不過，應用程式可以使用設定為 TA_UPDATECP fMode 參數的 fMode 參數呼叫 SetTextAlign 函式，以允許系統在每次應用程式呼叫指定裝置內容的 ExtTextOut 時，使用和更新目前的位置。設定此旗標時，系統會在後續的 ExtTextOut 呼叫上忽略 X 和 Y 參數。

針對 ExtTextOut 的 ANSI 版本， lpDx 陣列的 INT 值數目與 lpString 中有位元組相同。若為 DBCS 字元，只要兩個字節的總和加到所需的 dx，您就可以在前置位元組與尾端位元組之間分配 lpDx 專案的 dx。對於具有 ExtTextOut Unicode 版本的 DBCS 字元，每個 Unicode 字元都會取得單一 pdx 專案。

請注意，來自 GetTextExtentExPoint 的 alpDx 值與 ExtTextOut 的 lpDx 值不同。若要在 lpDx 中使用 alpDx 值，您必須先處理它們。

ExtTextOut 會在需要時使用 Uniscribe ，導致字型後援。 ETO_IGNORELANGUAGE旗標將會禁止此行為，不應傳遞。

此外，ExtTextOut 會在轉換至核心模式之前執行內部批次呼叫，降低 PolyTextOut 與 ExtTextOut 使用方式時的一些效能考慮。

提示

強烈建議使用PolyTextOut進行新式開發，因為其能夠處理不同語言的顯示。

範例

For an example, see "Setting Fonts for Menu-Item Text Strings" in Using Menus.

注意

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

規格需求

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