DrawText 函式 (winuser.h)

發行項
01/10/2024

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

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

語法

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

參數

[in] hdc

裝置內容的句柄。

[in, out] lpchText

字串的指標，指定要繪製的文字。如果 nCount 參數是 -1，字串必須以 Null 結尾。

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

[in] cchText

字串的長度，以字元為單位。如果 nCount 是 -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	展開定位字元。每個定位預設有八個字元。 DT_WORD_ELLIPSIS、DT_PATH_ELLIPSIS和DT_END_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時，DrawText 會稍微快一點。
DT_NOFULLWIDTHCHARBREAK	防止 DBCS 的換行符 (雙寬字元字串) ，使換行規則相當於 SBCS 字串。例如，這可以在韓文視窗中使用，以取得圖示標籤標的可讀性。除非指定DT_WORDBREAK，否則這個值沒有作用。
DT_NOPREFIX	關閉前置字元的處理作業。一般而言， DrawText 會將助記鍵前置詞字元解譯為指示詞 &，以底線後面字元，並將助記字元前置字元 && 為指示詞，以列印單一 &。藉由指定DT_NOPREFIX，此處理會關閉。例如範例：輸入字串：“A&bc&&d” 正常：“Abc&d” DT_NOPREFIX：「A&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 正常：“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旗標。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	winuser.h (包含 Windows.h)
程式庫	User32.lib
Dll	User32.dll
API 集合	ext-ms-win-ntuser-misc-l1-1-0 (在 Windows 8) 中引進