ExtTextOutA 函式（wingdi.h）

發行項
11/20/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 呼叫 anSI 版本的 extTextOut，即使函式沒有執行任何動作，函式仍會傳回 true 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 參數所指向之陣列的字元儲存格原點和內容是以邏輯單位指定。字元儲存格原點定義為字元儲存格的左上角。

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

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

請注意，GetTextExtentExPointalpDx 值與 ExtTextOutlpDx 值不同。若要在 lpDx中使用 alpDx 值，您必須先處理它們。

ExtTextOut 會在必要時使用 Uniscribe，進而產生字型後援。 ETO_IGNORELANGUAGE旗標會抑制此行為，不應傳遞。

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

提示

ExtTextOut 強烈建議 PolyTextOut，因為它能夠處理不同語言的顯示。

例子

如需範例，請參閱使用功能表中的<設定 Menu-Item 文字字串的字型>。

注意

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

要求

要求	價值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平臺	窗戶
標頭	wingdi.h （包括 Windows.h）
連結庫	Gdi32.lib
DLL	Gdi32.dll