共用方式為


ExtTextOutA 函式 (wingdi.h)

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 呼叫上忽略 XY 參數。

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

請注意,來自 GetTextExtentExPointalpDx 值與 ExtTextOutlpDx 值不同。 若要在 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

另請參閱

字型和文字函式

字型和文字概觀

GetTextAlign

矩形

SelectObject

SetBkColor

SetTextAlign

SetTextColor