GetTextExtentExPointW 関数 (wingdi.h)

  • [アーティクル]

GetTextExtentExPoint 関数は、指定したスペース内に収まる指定した文字列内の文字数を取得し、それらの各文字のテキスト範囲を配列に格納します。 (テキスト範囲は、スペースの先頭とスペースに収まる文字との間の距離です)。この情報は、ワードラッピング計算に役立ちます。

構文

BOOL GetTextExtentExPointW(
  [in]  HDC     hdc,
  [in]  LPCWSTR 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 コード ページの文字はそれぞれ 1 バイトになりますが、DBCS コード ページのほとんどの文字は 2 バイトになります。Unicode 関数の場合、現在定義されているほとんどの Unicode 文字 (Basic 多言語プレーン (BMP) の文字) は 1 つの WORD で、Unicode サロゲートは 2 つの WORD です。

[in] nMaxExtent

書式設定された文字列の最大許容幅 (論理単位)。

[out] lpnFit

nMaxExtent パラメーターで指定されたスペースに収まる最大文字数のカウントを受け取る整数へのポインター。 lpnFit パラメーターが NULL の場合、nMaxExtent パラメーターは無視されます。

[out] lpnDx

部分的な文字列エクステントを受け取る整数の配列へのポインター。 配列内の各要素は、文字列の先頭と nMaxExtent パラメーターで指定されたスペースに収まる文字の 1 つの間の距離を論理単位で指定します。 この配列は、配列全体が内部的に使用されるため、 cchString パラメーターで指定された文字と同数以上の要素を持つ必要があります。 関数は、 lpnFit パラメーターで指定された文字数だけ有効なエクステントを配列に入力します。 配列の残りの部分の値はすべて無視する必要があります。 alpDx が NULL の場合、関数は文字列の幅の一部を計算しません。

文字のシーケンスが任意の数のグリフで表される複雑なスクリプトの場合、 alpDx 配列内の値は、 lpnFit パラメーターで指定された数まで、コード ポイントと 1 対 1 と一致します。 ここでも、 alpDx 配列の残りの値は無視する必要があります。

[out] lpSize

文字列の次元を論理単位で受け取る SIZE 構造体へのポインター。 このパラメーターを NULL にすることはできません。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。

注釈

lpnFit パラメーターと alpDx パラメーターの両方が NULL の場合、GetTextExtentExPoint 関数の呼び出しは、GetTextExtentPoint 関数の呼び出しと同じです。

ANSI バージョンの GetTextExtentExPoint の場合、 lpDx 配列の INT 値の数は lpString のバイト数と同じです。 DBCS 文字の 2 バイトに対応する INT 値は、複合文字全体の各エクステントです。

GetTextExtentExPoint の alpDx 値は、ExtTextOut の lpDx 値と同じではないことに注意してください。 lpDx で alpDx 値を使用するには、まずそれらを処理する必要があります。

この関数は、テキスト範囲を返すとき、テキストが水平、つまりエスケープメントが常に 0 であることを前提としています。 これは、テキストの水平方向と垂直方向の両方の測定値に当てはまります。 0 以外のエスケープメントを指定するフォントを使用する場合でも、この関数はテキスト範囲を計算するときに角度を使用しません。 アプリでは、明示的に変換する必要があります。 ただし、グラフィックス モードが GM_ADVANCED に設定されていて、文字の向きが印刷方向から 90 度の場合、この関数が返す値はこの規則に従いません。 特定の文字列の文字の向きと印刷の向きが一致する場合、この関数は SIZE 構造体の文字列の次元を { cx : 116, cy : 18 } として返します。 同じ文字列に対して文字の向きと印刷の向きが 90 度離れている場合、この関数は SIZE 構造体の文字列の次元を { cx : 18, cy : 116 } として返します。

この関数は、文字列内の連続する各文字の範囲を返します。 これらを論理単位に丸めると、 GetCharWidth から返される結果とは異なる結果が得られます。この結果は、論理単位に丸められた個々の文字の幅を返します。

注意

wingdi.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして GetTextExtentExPoint を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー wingdi.h (Windows.h を含む)
Library Gdi32.lib
[DLL] Gdi32.dll

こちらもご覧ください

フォント関数とテキスト関数

フォントとテキストの概要

GetTextExtentPoint

SIZE