Функция GetCharacterPlacement

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

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

Синтаксис

DWORD GetCharacterPlacement(
  HDC hdc,                 // дескриптор DC
LPCTSTR lpString,          // строка символов
  int nCount,              // число символов
  int nMaxExtent,          // максимальная протяженность строки
  LPGCP_RESULTS lpResults, // размещение результата
  DWORD dwFlags            // размещение параметров
);

Параметры

hdc
[in] Дескриптор контекста устройства.
lpString
[in] Указатель на строку символов для обработки.
nCount
[in] Устанавливает длину строки. Для функции ANSI это - итоговое число байтов (BYTE), а для функции Unicode это - итоговое число СЛОВ (WORD). 
Обратите внимание! на то, что для функции ANSI, буквы в кодовых страницах SBCS (набора однобайтовых символов) берут  по одному байту каждый, в то время как большинство букв в кодовых страницах DBCS (набора двухбайтовых символов)   берут два байта; для функции Unicode наиболее правильное определение символов Unicode (это в Основной Многоязычной плоскости - Basic Multilingual Plane(BMP)) - одно слово (WORD), в то время как в заменителях Unicode - это два слова  (WORD).

Windows 95/98/Me: Это значение не может быть больше чем 8192.

nMaxExtent
[in] Устанавливает максимальную протяженность (в логических единицах измерения), при которой обрабатывается строка. Символы которые выходят за пределы этой протяженности, при обработке игнорируются. Вычисления для любой требуемой расстановки или массивов глифов применяются только ко включенным в эти пределы символам. Этот параметр используется, только тогда, если в  параметре dwFlags устанавливается значение GCP_MAXEXTENT. Поскольку функция обрабатывает вводимую строку, каждый символ и его протяженность добавляется к выводу, протяженности и другим массивам, только тогда, если полная протяженность еще не вышла за пределы максимума. Как только ограничение достигнуто, обработка будет остановлена.
lpResults
[in/out] Указатель на структуру GCP_RESULTS, которая принимает результаты работы функции.
dwFlags
[in] Устанавливает, как обрабатывать строку в затребованных массивах. Этот параметр может состоять из одного или нескольких нижеследующих значений.

 

Значение Предназначение
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).

Обратите внимание! на то, что только, потому что функция GetFontLanguageInfo возвращает флажок GCP_KASHIDA не подразумевает, что это должно использоваться при вызове функции GetCharacterPlacement, это лишь то,  что параметр доступен.
GCP_LIGATE Лигатуры (сшивки символов) используются везде, где символы сшиваются. Лигатура встречается там, где один глиф используется для двух или больше символов. Например, символы а и 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. Если не требуется предустановленный порядок , устанавливаются нулевые значения. Эти значения могут быть объединены с другими значениями, если устанавливается флажок GCP_CLASSIN .

Если значение GCP_REORDER не определено, параметр lpString  принимается таким, чтобы визуально порядок чтения был для языков, где он используется, а поля lpOutString и lpOrder  игнорируются.

Используйте функцию GetFontLanguageInfo, чтобы определить, поддерживает ли текущий шрифт переупорядочение.
GCP_SYMSWAPOFF Только для Семитских языков. Устанавливает, что изменяющие ориентацию в зависимости от  места символы не сбрасываются. Например, в строке с ориентацией справа налево , скобки "(" и ")" не изменяются на противоположные.
GCP_USEKERNING Чтобы использовать пары букв с уменьшенным межбуквенным просветом (кернинг) в шрифте (если это есть) при создании массивов размеров. Используйте функцию GetFontLanguageInfo, чтобы определить, поддерживает ли текущий шрифт кернинг.

Обратите внимание! на то, что только, потому что функция GetFontLanguageInfo возвращает флажок GCP_USEKERNING не подразумевает, что он должен использоваться при вызове функции GetCharacterPlacement. Это лишь то, что параметр доступен. Большинство шрифтов TrueType имеет таблицу кернинга, но Вы не должны использовать ее.

 

Рекомендуется, чтобы приложение использовало функцию 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

Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz