Функция GetCharacterPlacement извлекает информацию о строке символов, такую как ширины символов, позиция каретки, распределение в пределах строки и обработка, повышающая качество изображения глифа. Тип возвращенной информации зависит от параметра dwFlags и базируется на текущем выбранном шрифте в заданном контексте вывода на экран. Функция копирует информацию в указанную структуру GCP_RESULTS или в один или несколько массивов, указанных этой структурой.
Хотя эта функция и была когда-то отвечающей требованиям для того, чтобы работать со строками символов, потребность работать с увеличивающимся числом языков и шрифтов превратила ее в устаревшую. Она была заменена функциональными возможностями модуля Uniscribe (Универсального письма). Для подробной информации, см. главу О модуле Uniscribe.
Синтаксис
|
Обратите внимание! на то, что для функции ANSI, буквы в кодовых страницах SBCS (набора однобайтовых символов) берут по одному байту каждый, в то время как большинство букв в кодовых страницах DBCS (набора двухбайтовых символов) берут два байта; для функции Unicode наиболее правильное определение символов Unicode (это в Основной Многоязычной плоскости - Basic Multilingual Plane(BMP)) - одно слово (WORD), в то время как в заменителях Unicode - это два слова (WORD). |
Windows 95/98/Me: Это значение не может быть больше чем 8192.
Значение | Предназначение | |
---|---|---|
GCP_CLASSIN | Устанавливает, что массив lpClass содержит предустановленные классификации символов. Классификации могут быть те же самые, что и при выводе. Если специфическая классификация для символа не известна, соответствующая локализация в массиве должна быть установлена на нуль. Подробную информации о классификациях, см. статью о GCP_RESULTS. Это полезно только тогда, если функция GetFontLanguageInfo возвратила флажок GCP_REORDER. | |
GCP_DIACRITIC |
Выясняет, как
обрабатываются диакритические знаки в
строке. Если это значение не установлено,
диакритические знаки рассматриваются
как символы нулевой ширины. Например,
строка еврейского языка может содержать
диакритические знаки, но Вы не сможете
при всем своем желании показать их на
экране.
Используйте функцию GetFontLanguageInfo, чтобы определить, поддерживает ли шрифт диакритические знаки. Если он это делает, Вы можете использовать или не использовать флажок GCP_DIACRITIC при вызове функции GetCharacterPlacement, в зависимости от потребностей вашего приложения. |
|
GCP_DISPLAYZWG | В кодовой странице для языков, которые нуждаются в изменении порядка чтения или в других формах глифа в зависимости от позиции символов внутри слова, часто появляются не отображаемые на экране символы. Например, в еврейской кодовой странице, есть маркеры слева направо и справа налево , которые помогают определять конечное позиционирование символов внутри строк вывода. Обычно они не показываются на экране и удаляются из массивов lpDx и lpGlyphs. Вы можете использовать флажок GCP_DISPLAYZWG, чтобы показать на экране эти символы. | |
GCP_GLYPHSHAPE | Устанавливает, что некоторые или все символы в строке должны быть отображены, используя формы отличающиеся от стандартной, которая определена в текущем выбранном шрифте для текущей кодовой страницы. Некоторые языки, такие как арабский язык, не могут поддерживать создание глифа, если это значение не задается. Как правило, если функция GetFontLanguageInfo возвращает это значение для строки, это значение должно использоваться функцией GetCharacterPlacement. | |
GCP_JUSTIFY | Корректирует длины строк в массиве lpDx так, чтобы длина строки была та же самая, что и в параметре nMaxExtent. Флажок GCP_JUSTIFY может использоваться только вместе с флажком GCP_MAXEXTENT. | |
GCP_KASHIDA |
Использует кашиды (Kashida
- протяжка в арабском письме) так
же или вместо корректировки
протяженности, чтобы изменить длину
строки так, чтобы она была равна
значению, заданному параметром nMaxExtent.
В массиве lpDx кашида обозначается
отрицательным индексом выравнивания.
Флажок GCP_KASHIDA может
использоваться только вместе с флажком
GCP_JUSTIFY, и только
тогда, если шрифт (и язык) поддерживает
кашиды. Используйте функцию GetFontLanguageInfo,
чтобы определить, поддерживает ли
текущий шрифт кашиды.
Использование кашид, чтобы выровнять строку может привести к числу требуемых глифов больше чем число символов во вводимой строке. Из-за этого, когда используются протяжки (кашиды) , приложение не может предполагать, что устанавливаемые массивы, по размеру вводимой строки, могут быть не достаточными. (Возможный максимум должен быть приблизительно dxPageWidth/dxAveCharWidth, где dxPageWidth - ширина документа, а dxAveCharWidth - средняя ширина символа, которая возвращается при вызове функции GetTextMetrics).
|
|
GCP_LIGATE |
Лигатуры (сшивки
символов) используются везде, где
символы сшиваются. Лигатура встречается
там, где один глиф используется для двух
или больше символов. Например, символы а
и e могут сшиться в æ.
Однако, чтобы это использовать, и
языковая поддержка и шрифт должны
поддерживать обязательные глифы (по-английски,
выше пример, не будет обрабатываться
по умолчанию). Используйте функцию GetFontLanguageInfo, чтобы определить, поддерживает ли текущий шрифт лигатуру (сшивку символов). Если он это делает, а заданный максимум требуется для числа символов, которые сшиваются, установите это число в первом элементе массива lpGlyphs. Если требуется обычная лигатура, установите это значение в нуль. Если флажок GCP_LIGATE не установлен, никакой лигатуры не произойдет. За подробной информацией обратитесь к статье GCP_RESULTS. Если значение GCP_REORDER, которое обычно требуется для набора символов, не определено, то выводимые данные будут бессмысленными, если строка, пересылаемая в них еще не находится в визуальном состоянии (то есть результат, который получается помещением в LpGcpResults-> lpOutString при одном вызове функции 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. Если не требуется предустановленный порядок , устанавливаются нулевые значения. Эти значения могут быть объединены с другими значениями, если устанавливается флажок GCP_CLASSIN . Если значение GCP_REORDER не определено, параметр lpString принимается таким, чтобы визуально порядок чтения был для языков, где он используется, а поля lpOutString и lpOrder игнорируются. Используйте функцию GetFontLanguageInfo, чтобы определить, поддерживает ли текущий шрифт переупорядочение. |
|
GCP_SYMSWAPOFF | Только для Семитских языков. Устанавливает, что изменяющие ориентацию в зависимости от места символы не сбрасываются. Например, в строке с ориентацией справа налево , скобки "(" и ")" не изменяются на противоположные. | |
GCP_USEKERNING |
Чтобы использовать пары букв с
уменьшенным межбуквенным просветом (кернинг)
в шрифте (если это есть) при создании
массивов размеров. Используйте функцию GetFontLanguageInfo,
чтобы определить, поддерживает ли
текущий шрифт кернинг.
|
Рекомендуется, чтобы приложение использовало функцию GetFontLanguageInfo, для определения, допустимы ли значения GCP_DIACRITIC, GCP_DBCS, GCP_USEKERNING, GCP_LIGATE, GCP_REORDER, GCP_GLYPHSHAPE и GCP_KASHIDA для текущего выбранного шрифта. Если не допустимы, функция GetCharacterPlacement игнорирует значение.
Значение GCP_NODIACRITICS больше не определено и не должно использоваться.
Возвращаемые значенияЕсли функция завершается успешно, возвращаемое значение то же самое, что и возвращаемое значение из функции GetTextExtentPoint32, ширина и высота строки в логических единицах измерения.
Если функция завершается с ошибкой, величина возвращаемого значения - ноль.
Windows NT/2000/XP: Чтобы получить дополнительную информацию об ошибке, вызовите функцию GetLastError.
Замечания
Функция 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 конкретны для текущего шрифта в контексте устройства и используются только для написание текста в контексте устройства до тех пор, пока этот шрифт остается выбранным. |
Когда вычисляется выравнивание, если конечные символы в строке являются пробелами, функция, преобразует длину строки и удаляет пробелы до вычисления выравнивания. Если массив состоит только из пробелов, функция возвращает значение ошибки.
Обратите внимание! на то, что GetCharacterPlacement не производит те же самые действия для протяжки в арабском письме (кашиды) и выравнивания в среде Windows 98 / Me, как это делается в Windows NT / 2000/XP. Чтобы достигнуть слаженности действий во всех операционных системах, используйте модуль Uniscribe. |
Функция ExtTextOut ожидает запись lpDX для каждого байта строки набора двухбайтовых символов (DBCS), тогда как GetCharacterPlacement назначает запись lpDX для каждого глифа. Чтобы исправить это несоответствие при использовании этой комбинации функций, используйте или функцию GetGlyphIndices, или разворачивайте массив lpDX с записями нулевой ширины для соответствующего второго байта для пары байтов DBCS.
Windows NT/2000/XP: Если логическая ширина меньше, чем ширина ведущего символа во вводимой строке, член структуры GCP_RESULTS.nMaxFit возвращает неправильное значение. В этом случае, вызовите функцию GetCharacterPlacement для индексации глифа и массива lpDX. Затем используйте массив lpDX, чтобы сделать вычисление протяженности, используя занимаемую ширину каждым символом, где nMaxFit - число символов, глифы которых индексируя предварительную ширину, являются меньше, чем ширина ведущего символа.
Windows 95/98/Me: GetCharacterPlacementW поддерживается подпрограммой Microsoft Layer for Unicode. Чтобы использовать ее, Вы должны добавить некоторые файлы к вашему приложению, как изложено в требованиях этой подпрограммы для систем Windows 95/98/Me.
Обзор шрифты и текст, Функции, используемые шрифтами и текстом, ExtTextOut, GCP_RESULTS, GetCharABCWidths, GetCharWidth32, GetFontLanguageInfo, GetStringTypeEx, GetTextExtentPoint32, GetTextMetrics
Размещение и совместимость GetCharacterPlacement |
|
Windows. NET Server |
Да |
Windows XP |
Да |
Windows 2000 |
Да |
Windows NT |
Да версии 4.0 и выше |
Windows Me |
Да |
Windows 98 |
Да |
Windows 95 |
Да |
Используемая библиотека |
Gdi32.lib |
Заголовочный файл |
|
- объявлено в |
Wingdi.h |
- включено в |
Windows.h |
Unicode |
Реализуется как версии Unicode и ANSI в Windows NT /2000/XP. Поддерживается также подпрограммой Microsoft Layer for Unicode |
Замечания по платформе |
Не имеется |