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 會將連字元和 (&) 助記鍵前置詞解譯為指示詞，以將後面字元加上底線，並將雙 amper 和 (&&) 助記鍵前置詞字元解譯為指示詞，以列印單一 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

字型和文字函式

字型和文字概觀