DrawTextA 函式（winuser.h）

發行項
11/20/2024

DrawText 函式會在指定的矩形中繪製格式化的文字。它會根據指定的方法格式化文字（展開索引標籤、對齊字元、斷行等等）。

若要指定其他格式化選項，請使用 DrawTextEx 函式。

語法

int DrawTextA(
  [in]      HDC    hdc,
  [in, out] LPCSTR lpchText,
  [in]      int    cchText,
  [in, out] LPRECT lprc,
  [in]      UINT   format
);

參數

[in] hdc

裝置內容的句柄。

[in, out] lpchText

字串的指標，指定要繪製的文字。如果 cchText 參數為 -1，字串必須以 null 結束。

如果 uFormat 包含DT_MODIFYSTRING，函式最多可以為此字串加上四個額外的字元。包含字串的緩衝區應該足以容納這些額外的字元。

[in] cchText

字串的長度，以字元為單位。如果 cchText 為 -1，則會假設 lpchText 參數是 null 終止字串的指標，DrawText 會自動計算字元計數。

[in, out] lprc

RECT 結構的指標，其中包含要格式化文字的矩形（以邏輯座標表示）。

[in] format

格式化文字的方法。此參數可以是下列其中一或多個值。

價值	意義
DT_BOTTOM	將文字對齊矩形底部。這個值只會與 DT_SINGLELINE 值搭配使用。
DT_CALCRECT	決定矩形的寬度和高度。如果有多行文字，DrawText 會使用 lpRect 參數所指向的矩形寬度，並將矩形的基底延伸為系結最後一行文字。如果最大的單字比矩形寬，則會展開寬度。如果文字小於矩形的寬度，則會減少寬度。如果只有一行文字，DrawText 修改矩形的右側，使其將行的最後一個字元系結。不論是哪一種情況，DrawText 會傳回格式化文字的高度，但不會繪製文字。
DT_CENTER	在矩形中水準置中文字。
DT_EDITCONTROL	複製多行編輯控件的文字顯示特性。具體來說，平均字元寬度的計算方式與編輯控件相同，而且函式不會顯示部分可見的最後一行。
DT_END_ELLIPSIS	針對顯示的文字，如果字串的結尾不符合矩形，則會截斷並新增省略號。如果不在字串結尾的字超出矩形的限制，則會在不省略號的情況下截斷。除非指定DT_MODIFYSTRING旗標，否則不會修改字串。與DT_PATH_ELLIPSIS和DT_WORD_ELLIPSIS比較。
DT_EXPANDTABS	展開製表元。每個索引標籤的預設字元數為 8。 DT_WORD_ELLIPSIS、DT_PATH_ELLIPSIS和DT_END_ELLIPSIS值不能與DT_EXPANDTABS值搭配使用。
DT_EXTERNALLEADING	在行高中包含字型外部前置。一般而言，外部前置詞不會包含在文字行的高度中。
DT_HIDEPREFIX	忽略文字中的 ampersand （&）前置字元。後面的字母不會加上底線，但仍會處理其他助記鍵前置詞字元。例：輸入字串：“A&bc&&d” normal： “Abc&d” DT_HIDEPREFIX：“Abc&d” 與DT_NOPREFIX和DT_PREFIXONLY比較。
DT_INTERNAL	使用系統字型來計算文字計量。
DT_LEFT	將文字靠左對齊。
DT_MODIFYSTRING	修改指定的字串，以符合顯示的文字。除非指定DT_END_ELLIPSIS或DT_PATH_ELLIPSIS，否則這個值沒有任何作用。
DT_NOCLIP	繪製時不會裁剪。使用DT_NOCLIP時，DrawText 會比較快。
DT_NOFULLWIDTHCHARBREAK	防止 DBCS（雙寬字元字串）的換行符，使換行規則相當於 SBCS 字串。例如，這可用於韓文視窗，以取得圖示標籤標的可讀性。除非指定DT_WORDBREAK，否則這個值沒有任何作用。
DT_NOPREFIX	關閉前置字元的處理。一般而言，DrawText 會將助記音符號前置詞字元解譯為指示詞，以強調後面的 & 字元，並將助記符號前置詞字元 && 為指示詞，以列印單一 &。藉由指定DT_NOPREFIX，就會關閉此處理。例如例：輸入字串：“A&bc&&d” normal： “Abc&d” DT_NOPREFIX：“bc&bc&&d” 與DT_HIDEPREFIX和DT_PREFIXONLY比較。
DT_PATH_ELLIPSIS	針對顯示的文字，將字串中間的字元取代為省略號，讓結果符合指定的矩形。如果字串包含反斜杠（\\）字元，DT_PATH_ELLIPSIS最後一個反斜杠之後盡可能保留文字。除非指定DT_MODIFYSTRING旗標，否則不會修改字串。與DT_END_ELLIPSIS和DT_WORD_ELLIPSIS比較。
DT_PREFIXONLY	在安培德（&）前置字元之後，只繪製字元位置的底線。不會在字串中繪製任何其他字元。例如例：輸入字串：“A&bc&&d”n normal： “Abc&d” DT_PREFIXONLY： “ _ ” 與DT_HIDEPREFIX和DT_NOPREFIX比較。
DT_RIGHT	將文字靠右對齊。
DT_RTLREADING	當選取 hdc 為希伯來文或阿拉伯文字型時，以從右至左的閱讀順序配置雙向文字。所有文字的預設閱讀順序都是由左至右。
DT_SINGLELINE	僅顯示單行上的文字。歸位字元和換行字元不會中斷行。
DT_TABSTOP	設定製表位。 uFormat 參數的位 15-8（低序字的高階位元組）指定每個索引標籤的字元數。每個索引標籤的預設字元數為 8。 DT_CALCRECT、DT_EXTERNALLEADING、DT_INTERNAL、DT_NOCLIP和DT_NOPREFIX值不能與DT_TABSTOP值搭配使用。
DT_TOP	將文字對齊矩形頂端。
DT_VCENTER	垂直置中文字。這個值只會與 DT_SINGLELINE 值搭配使用。
DT_WORDBREAK	中斷字組。如果單字會延伸超過 lpRect 參數所指定的矩形邊緣，則字組會自動中斷。歸位字元換行序列也會中斷行。如果未指定此項目，輸出會位於一行。
DT_WORD_ELLIPSIS	截斷任何不符合矩形的字組，並新增省略號。與DT_END_ELLIPSIS和DT_PATH_ELLIPSIS比較。

傳回值

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

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

言論

DrawText 函式會使用裝置內容的選取字型、文字色彩和背景色彩來繪製文字。除非使用DT_NOCLIP格式，否則 DrawText 裁剪文字，使其不會出現在指定的矩形外。請注意，在文字字串或斜體文字中，可能會裁剪具有顯著懸空的文字，例如初始的 “W”。除非指定DT_SINGLELINE格式，否則所有格式都會假設有多行。

如果選取的字型對於指定的矩形而言太大，則 DrawText 函式不會嘗試取代較小的字型。

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

注意

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

要求

要求	價值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平臺	窗戶
標頭	winuser.h （包括 Windows.h）
連結庫	User32.lib
DLL	User32.dll
API 集	ext-ms-win-ntuser-misc-l1-1-0 （在 Windows 8 中引進）