Функция GetTextExtentExPointA (wingdi.h)

Статья
08/27/2023

Функция GetTextExtentExPoint извлекает количество символов в указанной строке, которое будет помещаться в пределах указанного пространства, и заполняет массив экстентом текста для каждого из этих символов. (Текстовый экстент — это расстояние между началом пробела и символом, который будет помещаться в пространстве.) Эти сведения полезны для вычислений с переносом по словам.

Синтаксис

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 он указывает длину строки в байтах, а для Юникода — длину строки в WORD. Обратите внимание, что для функции ANSI символы на кодовых страницах SBCS принимают по одному байту, а большинство символов на кодовых страницах DBCS — два байта. для функции Юникода наиболее определенные в настоящее время символы Юникода (в базовой многоязыковой плоскости (BMP)) являются одним словом WORD, а суррогаты Юникода — двумя WORD.

[in] nMaxExtent

Максимально допустимая ширина форматируемой строки в логических единицах.

[out] lpnFit

Указатель на целое число, которое получает максимальное количество символов, помещаемых в пространство, заданное параметром nMaxExtent . Если параметр lpnFit имеет значение NULL, параметр nMaxExtent игнорируется.

[out] lpnDx

Указатель на массив целых чисел, получающий частичные экстенты строки. Каждый элемент в массиве задает расстояние в логических единицах между началом строки и одним из символов, которые помещаются в пространстве, указанном параметром nMaxExtent . Этот массив должен содержать по меньшей мере столько элементов, сколько символов, заданных параметром cchString , так как весь массив используется внутри системы. Функция заполняет массив допустимыми экстентами для столько символов, сколько указано в параметре lpnFit . Любые значения в остальной части массива следует игнорировать. Если alpDx имеет значение NULL, функция не вычисляет частичную ширину строк.

Для сложных скриптов, где последовательность символов может быть представлена любым количеством глифов, значения в массиве alpDx вплоть до числа, указанного параметром lpnFit , соответствуют один к одному с кодовыми точками. Опять же, следует игнорировать остальные значения в массиве alpDx .

[out] lpSize

Указатель на структуру SIZE , которая получает измерения строки в логических единицах. Этот параметр не может иметь значение NULL.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение.

Для версии ANSI GetTextExtentExPoint массив lpDx имеет то же количество значений INT, что и байты в lpString. Значения INT, соответствующие двум байтам символа DBCS, являются экстентом всего составного символа.

Обратите внимание, что значения alpDx для GetTextExtentExPoint не совпадают со значениями lpDx для ExtTextOut. Чтобы использовать значения alpDx в lpDx, необходимо сначала обработать их.

Когда эта функция возвращает экстент текста, она предполагает, что текст является горизонтальным, то есть escapement всегда равен 0. Это верно для горизонтальных и вертикальных измерений текста. Даже если вы используете шрифт, указывающий ненулевой escapement, эта функция не использует угол при вычислении экстента текста. Приложение должно преобразовать его явным образом. Однако если для режима графики задано значение GM_ADVANCED и ориентация символа составляет 90 градусов от ориентации печати, значения, возвращаемые этой функцией, не соответствуют этому правилу. Если ориентация символа и ориентация печати совпадают для заданной строки, эта функция возвращает размеры строки в структуре SIZE в виде { cx : 116, cy : 18 }. Если ориентация символа и ориентация печати находятся на 90 градусов друг от друга для одной строки, эта функция возвращает размеры строки в структуре SIZE в виде { cx : 18, cy : 116 }.

Эта функция возвращает экстент каждого последовательного символа в строке. Если они округляются до логических единиц, результаты будут отличаться от результатов, возвращаемых методом GetCharWidth, который возвращает ширину каждого отдельного символа, округленного до логических единиц.

Примечание

Заголовок wingdi.h определяет GetTextExtentExPoint в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	wingdi.h (включая Windows.h)
Библиотека	Gdi32.lib
DLL	Gdi32.dll

См. также раздел

Функции шрифта и текста

Общие сведения о шрифтах и тексте

GetTextExtentPoint

SIZE

Поделиться через