DrawTextExA 函式 (winuser.h)

DrawTextEx函式會繪製指定矩形中的格式化文字。

語法

int DrawTextExA(
  [in]      HDC              hdc,
  [in, out] LPSTR            lpchText,
  [in]      int              cchText,
  [in, out] LPRECT           lprc,
  [in]      UINT             format,
  [in]      LPDRAWTEXTPARAMS lpdtp
);

參數

[in] hdc

要在其中繪製之裝置內容的控制碼。

[in, out] lpchText

字串的指標,其中包含要繪製的文字。 如果 cchText 參數是 -1,字串必須以 Null 終止。

如果 dwDTFormat 包含DT_MODIFYSTRING,此函式最多可以將四個額外的字元新增至此字串。 包含字串的緩衝區應該夠大,以容納這些額外的字元。

[in] cchText

lpchText所指向之字串的長度。 如果 cchText 是 -1,則會假設 lpchText 參數是 Null 終止字串的指標, 而 DrawTextEx 會自動計算字元計數。

[in, out] lprc

RECT結構的指標,其中包含要格式化文字之邏輯座標中的矩形。

[in] format

格式化選項。 此參數可以是下列一或多個值。

意義
DT_BOTTOM
對齊矩形底部的文字。 這個值只會與 DT_SINGLELINE 值搭配使用。
DT_CALCRECT
決定矩形的寬度和高度。 如果有多行文字, DrawTextEx 會使用 lprc 參數指向的矩形寬度,並將矩形的基底延伸至系結最後一行文字。 如果只有一行文字, DrawTextEx 會修改矩形右側,使其系結該行的最後一個字元。 在這兩種情況下, DrawTextEx 會傳回格式化文字的高度,但不會繪製文字。
DT_CENTER
將矩形中的文字水準置中。
DT_EDITCONTROL
複製多行編輯控制項的文字顯示特性。 具體而言,平均字元寬度的計算方式與編輯控制項相同,而且函式不會顯示部分可見的最後一行。
DT_END_ELLIPSIS
針對顯示的文字,將字串結尾取代為省略號,讓結果符合指定的矩形。 任何字 (不在字串結尾) 超出矩形限制的字組都會截斷,而不會省略號。 除非指定DT_MODIFYSTRING旗標,否則不會修改字串。

與DT_PATH_ELLIPSIS和DT_WORD_ELLIPSIS進行比較。

DT_EXPANDTABS
展開定位字元。 每個定位預設有八個字元。
DT_EXTERNALLEADING
在行高中包含字型外部前置字元。 一般而言,外部前置詞不會包含在文字行的高度中。
DT_HIDEPREFIX
忽略文字中的連字號和 (&) 前置字元。 後面的字母不會加上底線,但仍會處理其他助記字元前置字元。

範例:

輸入字串:「A & bc && d」

一般:「Abc & d」

DT_HIDEPREFIX:「Abc & d」

與DT_NOPREFIX和DT_PREFIXONLY進行比較。

DT_INTERNAL
使用系統字型,以計算文字度量資訊 (Metric)。
DT_LEFT
將文字靠左對齊。
DT_MODIFYSTRING
修改指定的字串,以符合顯示的文字。 除非指定DT_END_ELLIPSIS或DT_PATH_ELLIPSIS,否則這個值沒有任何作用。
DT_NOCLIP
不裁剪的繪製。 使用DT_NOCLIP時,DrawTextEx會稍微快一點。
DT_NOFULLWIDTHCHARBREAK
防止 DBCS (雙寬字元字串的分行符號) ,使換行規則相當於 SBCS 字串。 例如,這可以在韓文視窗中使用,以取得圖示標籤的可讀性。 除非指定DT_WORDBREAK,否則這個值沒有作用。
DT_NOPREFIX
關閉前置字元的處理作業。 一般而言, DrawTextEx 會將 ampersand (&) 助記詞前置詞字元解譯為指示詞,以底線底線後面的字元,而雙 ampersand () && 助記字元做為指示詞,以列印單一 ampersand。 藉由指定DT_NOPREFIX,此處理會關閉。 與DT_HIDEPREFIX和DT_PREFIXONLY比較
DT_PATH_ELLIPSIS
針對顯示的文字,將字串中間的字元取代為省略號,讓結果符合指定的矩形。 如果字串包含反斜線 (\\) 字元,則DT_PATH_ELLIPSIS最後一個反斜線之後盡可能保留文字。 除非指定DT_MODIFYSTRING旗標,否則不會修改字串。

與DT_END_ELLIPSIS和DT_WORD_ELLIPSIS進行比較。

DT_PREFIXONLY
只繪製位於) & 前置字元後面的字元位置底線 (。 不會在字串中繪製任何字元。

範例:

輸入字串:「A & bc && d」

一般:「Abc & d」

PREFIXONLY: 「 _ 」

與DT_NOPREFIX和DT_HIDEPREFIX比較。

DT_RIGHT
將文字靠右對齊。
DT_RTLREADING
當選取 hdc 的字型是希伯來文或阿拉伯文字型時,以從右至左讀取順序配置雙向文字。 所有文字的預設讀取順序都是由左至右。
DT_SINGLELINE
只顯示單行上的文字。 歸位字元和換行字元不會中斷行。
DT_TABSTOP
設定制表位。 lpDTParams參數所指向的DRAWTEXTPARAMS結構會指定每個定位停駐點的平均字元寬度數目。
DT_TOP
將文字對齊矩形頂端。
DT_VCENTER
垂直置中文字。 這個值只會與 DT_SINGLELINE 值搭配使用。
DT_WORDBREAK
中斷單字。 如果單字延伸超過 lprc 參數所指定的矩形邊緣,文字之間會自動中斷行。 歸位字元換行序列也會中斷行。
DT_WORD_ELLIPSIS
截斷任何不符合矩形的字組,並新增省略號。

與DT_END_ELLIPSIS和DT_PATH_ELLIPSIS比較。

[in] lpdtp

DRAWTEXTPARAMS結構的指標,指定其他格式選項。 此參數可以是 Null

傳回值

如果函式成功,則傳回值會是邏輯單元中的文字高度。 如果指定DT_VCENTER或DT_BOTTOM,則傳回值會是繪製 lprc->top 文字底部的位移

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

備註

DrawTextEx函式只支援逸出和方向都是零的字型。

裝置內容的文字對齊模式必須包含TA_LEFT、TA_TOP和TA_NOUPDATECP旗標。

注意

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

規格需求

   
最低支援的用戶端 Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平臺 Windows
標頭 winuser.h (包含 Windows.h)
程式庫 User32.lib
DLL User32.dll
API 集合 ext-ms-win-ntuser-misc-l1-2-0 (Windows 8.1)

另請參閱

DRAWTEXTPARAMS

DrawText

字型和文字函式

字型和文字概觀