структура GCP_RESULTSA (wingdi.h)
Структура GCP_RESULTS содержит сведения о символах в строке. Эта структура получает результаты функции GetCharacterPlacement . Для некоторых языков первый элемент в массивах может содержать дополнительные сведения, зависящие от языка.
Синтаксис
typedef struct tagGCP_RESULTSA {
DWORD lStructSize;
LPSTR lpOutString;
UINT *lpOrder;
int *lpDx;
int *lpCaretPos;
LPSTR lpClass;
LPWSTR lpGlyphs;
UINT nGlyphs;
int nMaxFit;
} GCP_RESULTSA, *LPGCP_RESULTSA;
Члены
lStructSize
Размер структуры (в байтах).
lpOutString
Указатель на буфер, который получает выходную строку, или имеет значение NULL , если строка вывода не требуется. Выходная строка — это версия исходной строки в порядке, который будет отображаться на указанном устройстве. Как правило, выходная строка идентична исходной строке, но может отличаться, если строка нуждается в переупорядочении и установлен флаг GCP_REORDER или если исходная строка превышает максимальный экстент и установлен флаг GCP_MAXEXTENT.
lpOrder
Указатель на массив, который получает упорядоченные индексы, или имеет значение NULL , если индексы упорядочения не нужны. Однако его значение зависит от других элементов GCP_RESULTS. Если возвращаются индексы глифов, индексы относятся к массиву lpGlyphs ; Если индексы глифов не возвращаются и запрашивается lpOrder , индексы предназначены для lpOutString. Например, в последнем случае значение lpOrder[i] — это позиция lpString[i] в выходной строке lpOutString.
Обычно это используется, когда GetFontLanguageInfo возвращает флаг GCP_REORDER, который указывает, что исходная строка нуждается в переупорядочении. Например, на иврите, в котором текст выполняется справа налево, массив lpOrder предоставляет точное расположение каждого элемента в исходной строке.
lpDx
Указатель на массив, который получает расстояния между смежными символьными ячейками или имеет значение NULL , если эти расстояния не требуются. Если отрисовка глифов выполнена, расстояния будут использоваться для глифов, а не символов, поэтому результирующий массив можно использовать с функцией ExtTextOut .
Расстояния в этом массиве находятся в порядке отображения. Чтобы найти расстояние для i-го символа в исходной строке, используйте массив lpOrder следующим образом:
width = lpDx[lpOrder[i]];
lpCaretPos
Указатель на массив, который получает значения позиции курсора или имеет значение NULL , если позиции курсора не нужны. Каждое значение задает позицию курсора непосредственно перед соответствующим символом. В некоторых языках курсор для каждого символа может находиться не сразу слева от символа. Например, на иврите, в котором текст выполняется справа налево, положение курсора находится справа от символа. Если упорядочение глифов выполнено, lpCaretPos соответствует исходной строке, а не выходной строке. Это означает, что некоторые смежные значения могут быть одинаковыми.
Значения в этом массиве находятся в порядке ввода. Чтобы найти значение позиции курсора для i-го символа в исходной строке, используйте массив следующим образом:
position = lpCaretPos[i];
lpClass
Указатель на массив, содержащий и (или) получающий классификации символов. Значения указывают, как выкладывать символы в строке и похожи (но не идентичны) значениям CT_CTYPE2, возвращаемым функцией GetStringTypeEx . Для каждого элемента массива можно задать нулевое или одно из следующих значений.
Кроме того, при указании значений в массиве lpClass с флагом GCP_CLASSIN можно использовать следующее.
Для языков, использующих флаг GCP_REORDER, с флагом GCP_CLASSIN также можно использовать следующие значения. В отличие от предыдущих значений, которые можно использовать в любом месте массива lpClass , все следующие значения используются только в первом расположении массива. Все они объединяются с другими классификациями.
Обратите внимание, что GCPCLASS_PREBOUNDLTR и GCPCLASS_PREBOUNDRTL являются взаимоисключающими, как и GCPCLASSPOSTBOUNDLTR и GCPCLASSPOSTBOUNDRTL.
Чтобы принудительно выполнить макет символа определенным образом, предустановите классификацию для соответствующего элемента массива; функция оставляет такие предустановленные классификации без изменений и вычисляет классификации только для элементов массива, для которых задано значение 0. Предустановленные классификации используются только в том случае, если установлен флаг GCP_CLASSIN и предоставлен массив lpClass .
Если GetFontLanguageInfo не возвращает GCP_REORDER для текущего шрифта, имеет смысл только GCPCLASS_LATIN значение.
lpGlyphs
Указатель на массив, который получает значения, определяющие глифы, используемые для отрисовки строки, или имеет значение NULL , если отрисовка глифов не требуется. Количество глифов в массиве может быть меньше числа символов в исходной строке, если строка содержит лигатурные глифы. Кроме того, если требуется переупорядочение, порядок глифов может быть не последовательным.
Этот массив полезен, если с строкой выполняется несколько операций, имеющих любую форму лигагирования, кернинга или переключения порядка. Использование значений в этом массиве для последующих операций экономит время, необходимое для создания индексов глифов каждый раз.
Этот массив всегда содержит индексы глифов, и значение ETO_GLYPH_INDEX всегда должно использоваться при использовании этого массива с функцией ExtTextOut .
При использовании GCP_LIGATE можно ограничить количество символов, которые будут связаны друг с другом. (В арабском языке, например, обычно используются трехзначные лигатуры.) Для этого необходимо задать максимальное необходимое значение в lpGcpResults-lpGlyphs>[0]. Если максимальное значение не требуется, установите для этого поля значение 0.
Для таких языков, как арабский, где GetFontLanguageInfo возвращает флаг GCP_GLYPHSHAPE, глифы для символа будут отличаться в зависимости от того, находится ли символ в начале, середине или конце слова. Как правило, первый символ во входной строке также будет первым символом в слове, а последний символ во входной строке будет рассматриваться как последний символ в слове. Однако если отображаемая строка является подмножеством полной строки, например при отображении раздела прокручиваемого текста, это может быть неверно. В таких случаях желательно, чтобы первые или последние символы формировались как не начальные или окончательные. Для этого, опять же, первое расположение в массиве lpGlyphs используется путем выполнения операции OR значения лигаций выше со значениями, GCPGLYPH_LINKBEFORE и (или) GCPGLYPH_LINKAFTER. Например, значение GCPGLYPH_LINKBEFORE | 2 означает, что двухзначные лигатуры являются максимальным обязательным, а первый символ в строке должен рассматриваться так, как если бы он был в середине слова.
nGlyphs
На входных данных для этого элемента необходимо задать размер массивов, на которые указывают элементы указателя массива. В выходных данных для этого параметра задается число заполненных глифов в выходных массивах. Если подстановка глифов не требуется (т. е. каждый символ ввода сопоставляется с одним глифом), этот элемент будет таким же, как и для входных данных.
nMaxFit
Число символов, которые помещаются в экстенты, заданные параметром nMaxExtent функции GetCharacterPlacement . Если задано значение GCP_MAXEXTENT или GCP_JUSTIFY, это значение может быть меньше числа символов в исходной строке. Этот элемент задается независимо от того, указано ли значение GCP_MAXEXTENT или GCP_JUSTIFY. В отличие от nGlyphs, который указывает количество выходных глифов, nMaxFit относится к количеству символов из входной строки. Для латинских языков SBCS это будет то же самое.
Комментарии
Требуется ли lpGlyphs, lpOutString или нет, зависит от результатов вызова GetFontLanguageInfo .
В случае шрифта для такого языка, как английский, в котором не возвращаются флаги GCP_DBCS, GCP_REORDER, GCP_GLYPHSHAPE, GCP_LIGATE, GCP_DIACRITIC или GCP_KASHIDA, ни один из массивов не требуется для правильной работы. (Хотя это и не обязательно, их все равно можно использовать. Если используется массив lpOutString , он будет точно таким же, как lpInputString , переданный в GetCharacterPlacement.) Однако обратите внимание, что если используется GCP_MAXEXTENT, то lpOutString будет содержать усеченную строку, если она используется, а не точную копию оригинала.
В случае шрифтов для таких языков, как иврит, которые ИМЕЮТ переупорядочение, но обычно не имеют дополнительных фигур глифов, следует использовать lpOutString . Это позволит получить строку в удобочитаемом порядке. Однако массив lpGlyphs обычно не требуется. (Иврит может содержать дополнительные глифы, если шрифт является шрифтом TrueType/Open.)
В случае языков, таких как тайский или арабский, в которых GetFontLanguageInfo возвращает флаг GCP_GLYPHSHAPE, lpOutString предоставит удобочитаемый порядок строки, передаваемой в GetCharacterPlacement, но значениями по-прежнему будут неформированные символы. Для правильного отображения необходимо использовать массив lpGlyphs .
Примечание
Заголовок wingdi.h определяет GCP_RESULTS в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Верхняя часть | wingdi.h (включая Windows.h) |