Функция GetCharacterPlacementA (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 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 содержит предустановленные классификации для символов. Классификации могут быть теми же, что и для выходных данных. Если конкретная классификация символа неизвестна, необходимо задать для соответствующего расположения в массиве значение 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	Используйте лигаций везде, где символы 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. Это особенно полезно при повторной отрисовке одного и того же текста или при использовании межсимволового интервала для размещения курсора. Если выходной массив lpGlyphs используется в вызове ExtTextOut, необходимо задать флаг 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 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	wingdi.h (включая Windows.h)
Библиотека	Gdi32.lib
DLL	Gdi32.dll