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

Статья
08/27/2023

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

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

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

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

Синтаксис

DWORD GetCharacterPlacementW(
  [in]      HDC            hdc,
  [in]      LPCWSTR        lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSW 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 содержит предустановленные классификации символов. Классификации могут быть теми же, что и для выходных данных. Если конкретная классификация для символа неизвестна, необходимо задать для соответствующего расположения в массиве значение 0. Дополнительные сведения о классификациях см. в разделе GCP_RESULTS. Это полезно, только если GetFontLanguageInfo вернул флаг GCP_REORDER.
GCP_DIACRITIC	Определяет способ обработки диакритических символов в строке. Если это значение не задано, диакритические знаки обрабатываются как символы нулевой ширины. Например, строка на иврите может содержать диакритические знаки, но вы можете не отображать их. Используйте GetFontLanguageInfo , чтобы определить, поддерживает ли шрифт диакритические функции. В этом случае можно использовать флаг GCP_DIACRITIC в вызове GetCharacterPlacement в зависимости от потребностей приложения.
GCP_DISPLAYZWG	Для языков, которым требуется переупорядочение или различные фигуры глифов в зависимости от положения символов в слове, на кодовой странице часто появляются неразыгрываемые символы. Например, на кодовой странице на иврите есть маркеры слева направо и справа налево, которые помогают определить окончательное расположение символов в выходных строках. Обычно они не отображаются и удаляются из массивов 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	Используйте пары кернинга в шрифте (если таковые есть) при создании массивов ширины. Используйте GetFontLanguageInfo , чтобы определить, поддерживает ли текущий шрифт пары кернинга. Обратите внимание, что только то, что 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 или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


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