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

Статья
08/27/2023

Функция getCharacterPlacement извлекает сведения о строке символов, таких как ширина символов, расположение курсора, упорядочение в строке и отрисовка глифов. Тип возвращаемой информации зависит от параметра dwFlags и основан на выбранном шрифте в указанном контексте отображения. Функция копирует сведения в указанную структуру GCP_RESULTS или в один или несколько массивов, указанных структурой.

Хотя эта функция когда-то была достаточной для работы с символьными строками, необходимо работать с увеличением числа языков и скриптов, которые отрисовывали его устаревшим. Он был заменен функциональными возможностями модуля Uniscribe. Дополнительные сведения см. в Юниписи.

Рекомендуется использовать функцию GetFontLanguageInfo , чтобы определить, допустимы ли значения GCP_DIACRITIC, GCP_DBCS, GCP_USEKERNING, GCP_LIGATE, GCP_REORDER, GCP_GLYPHSHAPE и GCP_KASHIDA для выбранного шрифта. Если это недопустимо, GetCharacterPlacement игнорирует значение.

Значение GCP_NODIACRITICS больше не определено и не должно использоваться.

Синтаксис

DWORD GetCharacterPlacementA(
  [in]      HDC            hdc,
  [in]      LPCSTR         lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSA lpResults,
  [in]      DWORD          dwFlags
);

Параметры

[in] hdc

Дескриптор контекста устройства.

[in] lpString

Указатель на строку символа для обработки. Строка не должна быть завершена с нуля, так как nCount указывает длину строки.

[in] nCount

Длина строки, на которую указывает lpString.

[in] nMexExtent

Максимальная степень (в логических единицах), в которой обрабатывается строка. Символы, которые при обработке превышают эту степень, игнорируются. Вычисления для любых обязательных массивов упорядочивания или глифа применяются только к включенным символам. Этот параметр используется только в том случае, если значение GCP_MAXEXTENT указано в параметре dwFlags. Поскольку функция обрабатывает входную строку, каждый символ и его экстент добавляются в выходные данные, экстенты и другие массивы только в том случае, если общая степень еще не превысила максимальное значение. После достижения предела обработка остановится.

[in, out] lpResults

Указатель на GCP_RESULTS структуру, которая получает результаты функции.

[in] dwFlags

Указывает, как обработать строку в необходимые массивы. Этот параметр может быть одним или несколькими из следующих значений.

Ценность	Значение
GCP_CLASSIN	Указывает, что массив lpClass содержит предустановленные классификации для символов. Классификации могут совпадать с выходными данными. Если определенная классификация для символа не известна, соответствующее расположение в массиве должно быть равно нулю. Дополнительные сведения о классификациях см. в GCP_RESULTS. Это полезно, только если GetFontLanguageInfo вернул флаг GCP_REORDER.
GCP_DIACRITIC	Определяет способ обработки диакритических символов в строке. Если это значение не задано, диакритические символы обрабатываются как символы нулевой ширины. Например, строка иврита может содержать диакритические элементы, но вы не хотите их отображать. Используйте GetFontLanguageInfo, чтобы определить, поддерживает ли шрифт diacritics. Если это так, можно использовать или не использовать флаг GCP_DIACRITIC в вызове GetCharacterPlacementв зависимости от потребностей приложения.
GCP_DISPLAYZWG	Для языков, которым требуется переупорядочение или различные фигуры глифа в зависимости от позиций символов в слове, нераспространимые символы часто отображаются на кодовой странице. Например, на странице кода иврита есть маркеры слеваTo-Right и справаTo-Left направо, чтобы определить окончательное расположение символов в выходных строках. Обычно они не отображаются и удаляются из массивов lpGlyphs и lpDx. Для отображения этих символов можно использовать флаг GCP_DISPLAYZWG.
GCP_GLYPHSHAPE	Указывает, что некоторые или все символы в строке должны отображаться с помощью фигур, отличных от стандартных фигур, определенных в выбранном в данный момент шрифте текущей кодовой страницы. Некоторые языки, такие как арабский, не могут поддерживать создание глифов, если это значение не указано. Как правило, если GetFontLanguageInfo возвращает это значение для строки, это значение должно использоваться с GetCharacterPlacement.
GCP_JUSTIFY	Настраивает экстенты в массиве lpDx, чтобы длина строки совпадала с nMaxExtent. GCP_JUSTIFY можно использовать только в сочетании с GCP_MAXEXTENT.
GCP_KASHIDA	Используйте Kashidas, а также или вместо того, чтобы изменить длину строки, чтобы оно было равно значению, заданному nMaxExtent. В массиве lpDx, kashida обозначается отрицательным индексом обоснования. GCP_KASHIDA можно использовать только в сочетании с GCP_JUSTIFY и только если шрифт (и язык) поддерживает Kashidas. Используйте GetFontLanguageInfo, чтобы определить, поддерживает ли текущий шрифт Kashidas. Использование Kashidas для оправдания строки может привести к тому, что количество глифов, необходимых для получения больше числа символов в входной строке. Из-за этого, когда используются Kashidas, приложение не может предположить, что установка массивов в качестве размера входной строки будет достаточной. (Максимально возможное значение будет приблизительно dxPageWidth/dxAveCharWidth, где dxPageWidth — это ширина документа и dxAveCharWidth — средняя ширина символа, возвращаемая из вызова GetTextMetrics . Обратите внимание, что только потому, что GetFontLanguageInfo возвращает флаг GCP_KASHIDA не означает, что он должен использоваться в вызове GetCharacterPlacement, просто что этот параметр доступен.
GCP_LIGATE	Используйте лигации везде, где символы лигают. Лигация возникает, когда один глиф используется для двух или нескольких символов. Например, буквы a и e могут лигать ?. Однако для использования этого языка поддержка языка и шрифт должны поддерживать необходимые глифы (пример не будет обрабатываться по умолчанию на английском языке). Используйте GetFontLanguageInfo, чтобы определить, поддерживает ли текущий шрифт лигирование. Если это делается и требуется определенное максимальное значение для числа символов, которые будут лигироваться, задайте число в первом элементе массива lpGlyphs. Если требуется обычная лигация, задайте для этого значения нулевое значение. Если GCP_LIGATE не указан, не будет выполняться лигирование. Дополнительные сведения см. в GCP_RESULTS. Если значение GCP_REORDER обычно требуется для набора символов, но не указано, выходные данные будут иметь смысл, если строка, передаваемая в нее, уже находится в визуальном порядке (то есть результат, который помещается в lpGcpResults->lpOutString в одном вызове GetCharacterPlacement является входной строкой второго вызова). Обратите внимание, что только так как GetFontLanguageInfo возвращает флаг GCP_LIGATE не означает, что он должен использоваться в вызове GetCharacterPlacement, просто что этот параметр доступен.
GCP_MAXEXTENT	Вычислительные экстенты строки только до тех пор, пока результирующая степень в логических единицах не превышает значения, указанные параметром nMaxExtent.
GCP_NEUTRALOVERRIDE	Только некоторые языки. Переопределите обычную обработку нейтральных символов и обработайте их как сильные символы, соответствующие порядку чтения строк. Полезно только с флагом GCP_REORDER.
GCP_NUMERICOVERRIDE	Только некоторые языки. Переопределите обычную обработку числовых символов и обработайте их как строгие символы, соответствующие порядку чтения строк. Полезно только с флагом GCP_REORDER.
GCP_NUMERICSLATIN	Только арабский/тайский. Используйте стандартные латинские глифы для чисел и переопределите системное значение по умолчанию. Чтобы определить, доступен ли этот параметр на языке шрифта, используйте GetStringTypeEx, чтобы узнать, поддерживает ли язык несколько числовых форматов.
GCP_NUMERICSLOCAL	Только арабский/тайский. Используйте локальные глифы для числовых символов и переопределите системное значение по умолчанию. Чтобы определить, доступен ли этот параметр на языке шрифта, используйте GetStringTypeEx, чтобы узнать, поддерживает ли язык несколько числовых форматов.
GCP_REORDER	Переупорядочение строки. Используется для языков, которые не являются SBCS и слева направо. Если это значение не указано, предполагается, что строка уже находится в порядке отображения. Если этот флаг задан для семитических языков и используется массив lpClass, первые два элемента массива используются для указания порядка чтения за пределами строки. GCP_CLASS_PREBOUNDRTL и GCP_CLASS_PREBOUNDLTR можно использовать для задания порядка. Если предустановленный порядок не требуется, задайте значения нулю. Эти значения можно объединить с другими значениями, если установлен флаг GCPCLASSIN. Если значение GCP_REORDER не указано, параметр lpString принимается для визуального упорядочения для языков, где используется это значение, и поля lpOutString и поля lpOrder игнорируются. Используйте GetFontLanguageInfo, чтобы определить, поддерживает ли текущий шрифт переупорядочение.
GCP_SYMSWAPOFF	Только семитские языки. Указывает, что переключения символов не сбрасываются. Например, в строке справа налево "(" и ")" не отменяются.
GCP_USEKERNING	При создании массивов ширины используйте пары kerning в шрифте (если таковые есть). Используйте GetFontLanguageInfo, чтобы определить, поддерживает ли текущий шрифт пары kerning. Обратите внимание, что только потому, что GetFontLanguageInfo возвращает флаг GCP_USEKERNING не означает, что он должен использоваться в вызове GetCharacterPlacement, просто что этот параметр доступен. Большинство шрифтов TrueType имеют таблицу kerning, но ее не нужно использовать.

Значение GCP_NODIACRITICS больше не определено и не должно использоваться.

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

Если функция выполнена успешно, возвращаемое значение равно ширине и высоте строки в логических единицах. Ширина — это слово с низким порядком, а высота — слово высокого порядка.

Если функция завершается ошибкой, возвращаемое значение равно нулю.

Замечания

GetCharacterPlacement гарантирует, что приложение может правильно обрабатывать текст независимо от международного параметра и типа доступных шрифтов. Приложения используют эту функцию перед использованием функции ExtTextOut и вместо функции GetTextExtentPoint32 (и иногда вместо функции GetCharWidth32 и GetCharABCWidths).

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

GetCharacterPlacement проверяет lpOrder, lpDX, lpCaretPos, lpOutString и lpGlyphs членов структуры GCP_RESULTS и заполняет соответствующие массивы, если эти элементы не заданы для NULL. Если GetCharacterPlacement не может заполнить массив, он задает соответствующий элемент NULL. Чтобы обеспечить получение допустимых сведений, приложение отвечает за установку члена на допустимый адрес перед вызовом функции и проверкой значения члена после вызова. Если указаны значения GCP_JUSTIFY или GCP_USEKERNING, lpDX и/или lpCaretPos должны иметь допустимые адреса.

Обратите внимание, что индексы глифов, возвращаемые в GCP_RESULTS.lpGlyphs, относятся к текущему шрифту в контексте устройства и должны использоваться только для рисования текста в контексте устройства, пока этот шрифт остается выбранным.

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

ExtTextOut ожидает записи lpDX для каждой байт строки DBCS, а GetCharacterPlacement назначает запись lpDX для каждого глифа. Чтобы исправить это несоответствие при использовании этой комбинации функций, используйте GetGlyphIndices или разверните массив lpDX с записями нулевой ширины для соответствующего второго байта пары байтов DBCS.

Если логическая ширина меньше ширины ведущего символа во входной строке, GCP_RESULTS.nMaxFit возвращает плохое значение. В этом случае вызовите GetCharacterPlacement для индексов глифов и массив lpDX. Затем используйте массив lpDX, чтобы выполнить вычисление экстентов с помощью расширенной ширины каждого символа, где nMaxFit — это число символов, ширина которых глиф индексов превышает ширину ведущего символа.

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	wingdi.h (включая Windows.h)
библиотеки	Gdi32.lib
DLL	Gdi32.dll