ホーム › Graphics.Gdi › GetTextExtentExPointI

GetTextExtentExPointI

関数

指定幅に収まるグリフ数と寸法を取得する。

DLLGDI32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// GDI32.dll
#include <windows.h>

BOOL GetTextExtentExPointI(
    HDC hdc,
    WORD* lpwszString,
    INT cwchString,
    INT nMaxExtent,
    INT* lpnFit,   // optional
    INT* lpnDx,   // optional
    SIZE* lpSize
);

パラメーター

名前	型	方向	説明
hdc	HDC	in	デバイスコンテキストへのハンドル。
lpwszString	WORD*	in	幅を取得する対象となるグリフインデックスの配列へのポインター。
cwchString	INT	in	lpwszString パラメーターが指すグリフインデックス配列内のグリフ数。
nMaxExtent	INT	in	書式設定された文字列の最大許容幅(論理単位)。
lpnFit	INT*	outoptional	nMaxExtent パラメーターで指定された幅に収まる最大文字数を受け取る整数へのポインター。lpnFit パラメーターが NULL の場合、nMaxExtent パラメーターは無視されます。
lpnDx	INT*	outoptional	部分的なグリフ幅を受け取る整数配列へのポインター。配列の各要素は、グリフインデックス配列の先頭から、nMaxExtent パラメーターで指定された幅に収まる各グリフまでの距離(論理単位)を示します。この配列は cwchString パラメーターで指定されたグリフインデックス数と同数以上の要素を持つべきですが、関数は lpnFit パラメーターで指定された数のグリフインデックスについてのみ幅を配列に格納します。lpnFit が NULL の場合、関数は部分的な文字列幅を計算しません。
lpSize	SIZE*	out	グリフインデックス配列の寸法(論理単位)を受け取る SIZE 構造体へのポインター。この値を NULL にすることはできません。

戻り値の型: BOOL

公式ドキュメント

GetTextExtentExPointI 関数は、指定された幅に収まる文字列中の文字数を取得し、それらの各文字のテキスト幅を配列に格納します。

戻り値

関数が成功した場合、戻り値は 0 以外の値です。

関数が失敗した場合、戻り値は 0 です。

解説(Remarks)

lpnFit パラメーターと lpnDx パラメーターの両方が NULL の場合、GetTextExtentExPointI 関数の呼び出しは GetTextExtentPointI 関数の呼び出しと同等です。

この関数がテキスト幅を返す際には、テキストが水平方向である、つまりエスケープメント(escapement)が常に 0 であると仮定します。これはテキストの水平方向の測定にも垂直方向の測定にも当てはまります。0 以外のエスケープメントを指定するフォントを使用した場合でも、この関数はテキスト幅の計算時にその角度を使用しません。アプリ側で明示的に変換する必要があります。ただし、グラフィックスモードが GM_ADVANCED に設定され、文字の向きが印刷の向きから 90 度回転している場合、この関数が返す値はこのルールに従いません。ある文字列について文字の向きと印刷の向きが一致している場合、この関数は文字列の寸法を SIZE 構造体に { cx : 116, cy : 18 } として返します。同じ文字列について文字の向きと印刷の向きが 90 度異なる場合、この関数は文字列の寸法を SIZE 構造体に { cx : 18, cy : 116 } として返します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// GDI32.dll
#include <windows.h>

BOOL GetTextExtentExPointI(
    HDC hdc,
    WORD* lpwszString,
    INT cwchString,
    INT nMaxExtent,
    INT* lpnFit,   // optional
    INT* lpnDx,   // optional
    SIZE* lpSize
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("GDI32.dll", ExactSpelling = true)]
static extern bool GetTextExtentExPointI(
    IntPtr hdc,   // HDC
    ref ushort lpwszString,   // WORD*
    int cwchString,   // INT
    int nMaxExtent,   // INT
    IntPtr lpnFit,   // INT* optional, out
    IntPtr lpnDx,   // INT* optional, out
    IntPtr lpSize   // SIZE* out
);

<DllImport("GDI32.dll", ExactSpelling:=True)>
Public Shared Function GetTextExtentExPointI(
    hdc As IntPtr,   ' HDC
    ByRef lpwszString As UShort,   ' WORD*
    cwchString As Integer,   ' INT
    nMaxExtent As Integer,   ' INT
    lpnFit As IntPtr,   ' INT* optional, out
    lpnDx As IntPtr,   ' INT* optional, out
    lpSize As IntPtr   ' SIZE* out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' hdc : HDC
' lpwszString : WORD*
' cwchString : INT
' nMaxExtent : INT
' lpnFit : INT* optional, out
' lpnDx : INT* optional, out
' lpSize : SIZE* out
Declare PtrSafe Function GetTextExtentExPointI Lib "gdi32" ( _
    ByVal hdc As LongPtr, _
    ByRef lpwszString As Integer, _
    ByVal cwchString As Long, _
    ByVal nMaxExtent As Long, _
    ByVal lpnFit As LongPtr, _
    ByVal lpnDx As LongPtr, _
    ByVal lpSize As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

GetTextExtentExPointI = ctypes.windll.gdi32.GetTextExtentExPointI
GetTextExtentExPointI.restype = wintypes.BOOL
GetTextExtentExPointI.argtypes = [
    wintypes.HANDLE,  # hdc : HDC
    ctypes.POINTER(ctypes.c_ushort),  # lpwszString : WORD*
    ctypes.c_int,  # cwchString : INT
    ctypes.c_int,  # nMaxExtent : INT
    ctypes.POINTER(ctypes.c_int),  # lpnFit : INT* optional, out
    ctypes.POINTER(ctypes.c_int),  # lpnDx : INT* optional, out
    ctypes.c_void_p,  # lpSize : SIZE* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('GDI32.dll')
GetTextExtentExPointI = Fiddle::Function.new(
  lib['GetTextExtentExPointI'],
  [
    Fiddle::TYPE_VOIDP,  # hdc : HDC
    Fiddle::TYPE_VOIDP,  # lpwszString : WORD*
    Fiddle::TYPE_INT,  # cwchString : INT
    Fiddle::TYPE_INT,  # nMaxExtent : INT
    Fiddle::TYPE_VOIDP,  # lpnFit : INT* optional, out
    Fiddle::TYPE_VOIDP,  # lpnDx : INT* optional, out
    Fiddle::TYPE_VOIDP,  # lpSize : SIZE* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "gdi32")]
extern "system" {
    fn GetTextExtentExPointI(
        hdc: *mut core::ffi::c_void,  // HDC
        lpwszString: *mut u16,  // WORD*
        cwchString: i32,  // INT
        nMaxExtent: i32,  // INT
        lpnFit: *mut i32,  // INT* optional, out
        lpnDx: *mut i32,  // INT* optional, out
        lpSize: *mut SIZE  // SIZE* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("GDI32.dll")]
public static extern bool GetTextExtentExPointI(IntPtr hdc, ref ushort lpwszString, int cwchString, int nMaxExtent, IntPtr lpnFit, IntPtr lpnDx, IntPtr lpSize);
"@
$api = Add-Type -MemberDefinition $sig -Name 'GDI32_GetTextExtentExPointI' -Namespace Win32 -PassThru
# $api::GetTextExtentExPointI(hdc, lpwszString, cwchString, nMaxExtent, lpnFit, lpnDx, lpSize)

#uselib "GDI32.dll"
#func global GetTextExtentExPointI "GetTextExtentExPointI" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; GetTextExtentExPointI hdc, varptr(lpwszString), cwchString, nMaxExtent, varptr(lpnFit), varptr(lpnDx), varptr(lpSize)   ; 戻り値は stat
; hdc : HDC -> "sptr"
; lpwszString : WORD* -> "sptr"
; cwchString : INT -> "sptr"
; nMaxExtent : INT -> "sptr"
; lpnFit : INT* optional, out -> "sptr"
; lpnDx : INT* optional, out -> "sptr"
; lpSize : SIZE* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "GDI32.dll"
#cfunc global GetTextExtentExPointI "GetTextExtentExPointI" sptr, var, int, int, var, var, var
; res = GetTextExtentExPointI(hdc, lpwszString, cwchString, nMaxExtent, lpnFit, lpnDx, lpSize)
; hdc : HDC -> "sptr"
; lpwszString : WORD* -> "var"
; cwchString : INT -> "int"
; nMaxExtent : INT -> "int"
; lpnFit : INT* optional, out -> "var"
; lpnDx : INT* optional, out -> "var"
; lpSize : SIZE* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "GDI32.dll"
#cfunc global GetTextExtentExPointI "GetTextExtentExPointI" sptr, sptr, int, int, sptr, sptr, sptr
; res = GetTextExtentExPointI(hdc, varptr(lpwszString), cwchString, nMaxExtent, varptr(lpnFit), varptr(lpnDx), varptr(lpSize))
; hdc : HDC -> "sptr"
; lpwszString : WORD* -> "sptr"
; cwchString : INT -> "int"
; nMaxExtent : INT -> "int"
; lpnFit : INT* optional, out -> "sptr"
; lpnDx : INT* optional, out -> "sptr"
; lpSize : SIZE* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。