GetTextExtentExPointA 函式 (wingdi.h)

  • 發行項

GetTextExtentExPoint 函式會擷取指定字串中的字元數，此字串會符合指定的空格，並以每個字元的文字範圍填滿數位。 (文字範圍是空格開頭與可放入 space 的字元之間的距離。) 這項資訊對於自動換行計算很有用。

語法

BOOL GetTextExtentExPointA(
  [in]  HDC    hdc,
  [in]  LPCSTR lpszString,
  [in]  int    cchString,
  [in]  int    nMaxExtent,
  [out] LPINT  lpnFit,
  [out] LPINT  lpnDx,
  [out] LPSIZE lpSize
);

參數

[in] hdc

裝置內容的句柄。

[in] lpszString

要擷取範圍之 Null 終止字串的指標。

[in] cchString

lpszStr 參數所指向之字串中的字元數。 如果是 ANSI，它會指定位元組的字串長度，而 Unicode 則會指定 WORD 中的字串長度。 請注意，針對 ANSI 函式，SBCS 代碼頁中的字元會各自採用一個字節，而 DBCS 代碼頁中的大部分字元則需要兩個字節;針對 Unicode 函式，大部分目前定義的 Unicode 字元 (基本多語系平面 (BMP) ) 是一個 WORD，而 Unicode 代理是兩個 WORD。

[in] nMaxExtent

格式化字串的最大允許寬度，以邏輯單位表示。

[out] lpnFit

整數的指標，可接收 nMaxExtent 參數所指定空間中最大字元數的計數。 當 lpnFit 參數為 NULL 時， 會忽略 nMaxExtent 參數。

[out] lpnDx

接收部分字串範圍之整數數位的指標。 陣列中的每個元素在字串的開頭與 符合 nMaxExtent 參數所指定空間的其中一個字元之間，都會以邏輯單位提供距離。 此陣列必須至少有 cchString 參數所指定的字元數目，因為整個陣列都是在內部使用。 函式會以 lpnFit 參數所指定的字元數目，以有效範圍填入數位。 應該忽略數位其餘部分的任何值。 如果 alpDx 為 NULL，則函式不會計算部分字串寬度。

對於複雜的腳本，其中字元序列可由任意數目的字元表示， 則alpDx 數位中的值會比對一對一與字碼點相符的 lpnFit 參數所指定的數位。 同樣地，您應該忽略 alpDx 陣列中其餘的值。

[out] lpSize

以邏輯單位接收字串維度 之 SIZE 結構的指標。 此參數不可為 NULL。

傳回值

如果函式成功，則傳回非零的值。

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

備註

如果 lpnFit 和 alpDx 參數都是 NULL，則呼叫 GetTextExtentExPoint 函式相當於呼叫 GetTextExtentPoint 函式。

針對 GetTextExtentExPoint 的 ANSI 版本， lpDx 陣列的 INT 值數目與 lpString 中有位元組相同。 對應至 DBCS 字元兩個字節的 INT 值，都是整個複合字元的範圍。

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

當此函式傳回文字範圍時，它會假設文字為水準，也就是逸出器一律為 0。 這適用於文字的水準和垂直度量。 即使您使用指定非零逸出項的字型，此函式也不會在計算文字範圍時使用角度。 應用程式必須明確地轉換它。 不過，當圖形模式設定為 GM_ADVANCED 且字元方向從列印方向為90度時，此函式傳回的值不會遵循此規則。 當指定字串的字元方向和列印方向相符時，此函式會以 { cx ： 116， cy ： 18 } 傳回 SIZE 結構中的字元串維度。 當相同字串的字元方向和列印方向相隔 90 度時，此函式會以 { cx ： 18， cy ： 116 } 傳回 SIZE 結構中的字元串維度。

此函式會傳回字串中每個連續字元的範圍。 當這些四捨五入為邏輯單元時，您得到的結果與 GetCharWidth 傳回的結果不同，其會傳回每個個別字元的寬度四捨五入為邏輯單元。

注意

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

規格需求

需求 值
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平台 Windows
標頭 wingdi.h (包含 Windows.h)
程式庫 Gdi32.lib
Dll Gdi32.dll

另請參閱

字型和文字函式

字型和文字概觀

GetTextExtentPoint

SIZE