Функция ScriptItemizeOpenType (usp10.h)

Статья
08/26/2023

Разбивает строку в Юникоде на отдельные фигурируемые элементы и предоставляет массив тегов признаков для каждого из фигурируемых элементов для обработки OpenType.

Синтаксис

HRESULT ScriptItemizeOpenType(
  [in]           const WCHAR          *pwcInChars,
  [in]           int                  cInChars,
  [in]           int                  cMaxItems,
  [in, optional] const SCRIPT_CONTROL *psControl,
  [in, optional] const SCRIPT_STATE   *psState,
  [out]          SCRIPT_ITEM          *pItems,
  [out]          OPENTYPE_TAG         *pScriptTags,
  [out]          int                  *pcItems
);

Параметры

[in] pwcInChars

Указатель на строку Юникода для элемента.

[in] cInChars

Количество символов в pwcInChars для элемента.

[in] cMaxItems

Максимальное число SCRIPT_ITEM структур, определяющих обрабатываемые элементы.

[in, optional] psControl

Указатель на структуру SCRIPT_CONTROL , указывающую тип элементов для выполнения.

Кроме того, приложение может задать для этого параметра значение NULL , если свойства SCRIPT_CONTROL не требуются. Дополнительные сведения см. в разделе «Примечания».

[in, optional] psState

Указатель на структуру SCRIPT_STATE , указывающую начальное двунаправленное состояние алгоритма.

Кроме того, приложение может задать для этого параметра значение NULL , если состояние скрипта не требуется. Дополнительные сведения см. в разделе «Примечания».

[out] pItems

Указатель на буфер, в котором функция извлекает SCRIPT_ITEM структуры, представляющие обработанные элементы. Длина буфера должна быть (cMaxItems + 1) * sizeof(SCRIPT_ITEM) в байтах. Недопустимо вызывать эту функцию с буфером, который обрабатывает менее двух SCRIPT_ITEM структур. Функция всегда добавляет элемент терминала в массив анализа элементов, чтобы длина элемента с отсчитываемого от нуля индекса "i" всегда была доступна следующим образом:

pItems[i+1].iCharPos - pItems[i].iCharPos;

[out] pScriptTags

Указатель на буфер, в котором функция извлекает массив OPENTYPE_TAG структур, представляющих теги скрипта. Длина буфера должна быть cMaxItems * sizeof(OPENTYPE_TAG) в байтах.

Примечание Если все символы в элементе являются нейтральными, значение этого параметра равно SCRIPT_TAG_UNKNOWN (0x00000000). Это может произойти, например, если элемент полностью состоит из знаков препинания.

[out] pcItems

Указатель на количество обработанных SCRIPT_ITEM структур.

Возвращаемое значение

Возвращает 0 в случае успеха. Функция возвращает ненулевое значение HRESULT, если это не удалось. Во всех случаях ошибок никакие элементы не обрабатываются полностью, а часть выходных данных не содержит определенных значений. Приложение может проверить возвращаемое значение с помощью макросов SUCCEEDED и FAILED .

Функция возвращает E_OUTOFMEMORY, если размер, указанный cMaxItems , слишком мал. Приложение может попытаться снова вызвать функцию с большим буфером.

Функция возвращает E_INVALIDARG при возникновении одного или нескольких из следующих условий:

PwcInChars имеет значение NULL.
CInChars имеет значение 0
PItems имеет значение NULL.
PScriptTags имеет значение NULL.
cMaxItems< 2

ScriptItemizeOpenType предпочтительнее, чем более старая функция ScriptItemize . Одним из преимуществ ScriptItemizeOpenType является доступность тегов компонентов для каждого элемента, допускающего фигуру.

Описание контекста, в котором обычно вызывается эта функция, см. в разделе Отображение текста с помощью uniscribe .

Функция разделяет элементы либо изменением подсистемы формирования, либо изменением направления.

Приложение может создавать несколько диапазонов или запусков, которые полностью входят в один элемент, из каждой структуры SCRIPT_ITEM, полученнойscriptItemizeOpenType. Однако не следует объединять несколько элементов в один запуск. При измерении или отрисовке приложение может вызывать ScriptShapeOpenType для каждого выполнения и должно передавать соответствующую структуру SCRIPT_ANALYSIS в структуре SCRIPT_ITEM , полученной scriptItemizeOpenType.

Если текст, обрабатываемый приложением, может содержать любое содержимое справа налево, приложение использует параметры psControl и psState при вызове ScriptItemizeOpenType. Однако приложение не должно делать этого и может обрабатывать двунаправленный текст вместо того, чтобы полагаться на Uniscribe для этого. Параметры psControl и psState полезны в некоторых сценариях строго слева направо, например, когда элемент fLinkStringBeforeSCRIPT_CONTROL не предназначен для сценариев справа налево. Приложение устанавливает для psControl и psStateзначение NULL , чтобы ScriptItemizeOpenType разбиение строки Юникода исключительно на символьный код.

Приложение может задать для всех параметров значения, отличные от NULL , чтобы функция выполняла полный двунаправленный анализ Юникода. Чтобы обеспечить правильный двунаправленный анализ в Юникоде, структура SCRIPT_STATE должна быть инициализирована в соответствии с порядком чтения в начале абзаца, а ScriptItemizeOpenType должна быть передана всему абзацу. В частности, элемент uBidiLevel следует инициализировать 0 для слева направо и 1 для справа налево.

Элемент fRTLSCRIPT_ANALYSIS указан в SCRIPT_ITEM. Элемент fNumericSCRIPT_PROPERTIES извлекается с помощью ScriptGetProperties. Эти элементы вместе обеспечивают ту же классификацию, что и член lpClassGCP_RESULTS, на который ссылается lpResults в GetCharacterPlacement.

Европейские цифры от U+0030 до U+0039 можно преобразовать в национальные цифры, как показано в следующей таблице.

SCRIPT_STATE.fDigitSubstitute	SCRIPT_CONTROL.fContextDigits	Фигуры цифр, отображаемые для Юникода от U+0030 до U+0039
FALSE	Любой	Европейские цифры
TRUE	FALSE	Как указано в элементе uDefaultLanguageSCRIPT_CONTROL.
TRUE	TRUE	Как и предыдущий строгий текст, по умолчанию используется элемент uDefaultLanguageSCRIPT_CONTROL.

В контекстном режиме цифр выполняется одно из следующих действий:

Если скрипт, заданный uDefaultLanguage , находится в том же направлении, что и выходные данные, все цифры, встречающиеся до первых букв, отображаются на языке , указанном uDefaultLanguage.
Если скрипт, заданный uDefaultLanguage , находится в противоположном направлении от выходных данных, все цифры, встречающиеся до первых букв, отображаются в европейских цифрах.

Например, если uDefaultLanguage указывает на LANG_ARABIC, начальные цифры Arabic-Indic при внедрении справа налево. Однако они находятся в европейских цифрах во встраивание слева направо.

Дополнительные сведения см. в разделе Фигуры цифр.

В следующей таблице приведены управляющие символы и определения Юникода, а также их влияние на SCRIPT_STATE членов. Дополнительные сведения об управляющих символах Юникода см. в разделе Стандарт Юникода.

Управляющие символы Юникода	Значение	Влияние на SCRIPT_STATE
NADS	Переопределите европейские цифры (NODS) национальными цифрами.	Задайте fDigitSubstitute.
КИВАЕТ	Используйте символьные фигуры, также называемые европейскими цифрами. См. раздел NADS.	Снимите флажок fDigitSubstitute.
ЖОПА	Активируйте переключение симметричные пары, например круглые скобки. Для этих символов слева и справа интерпретируются как открытие и закрытие. Это значение по умолчанию. См. раздел ISS.	Снимите флажок fInhibitSymSwap.
ISS	Запрет на переключение симметричными парами. См. раздел ASS.	Задайте fInhibitSymSwap.
AAFS	Активация формирования арабских форм для арабских форм презентации. См. раздел IAFS.	Задайте fCharShape.
IAFS	Препятствуют формированию арабской формы, т. е. лигатур и cursive связей, для арабских форм представления. Номинальные арабские символы не затрагиваются. Это значение по умолчанию. См. раздел AAFS.	Снимите флажок fCharShape.

Член fArabicNumContextSCRIPT_STATE поддерживает контекстное отображение цифр в тексте на арабском языке. Он указывает, отображаются ли цифры с помощью собственных арабских букв или европейских цифр. В начале абзаца этот элемент обычно должен быть инициализирован значением TRUE для арабского языкового стандарта или FALSE для любого другого языкового стандарта. Функция обновляет состояние скрипта по мере обработки строгого текста.

Выходной параметр pScriptTags указывает на массив с записями, параллельными элементам. Для каждого элемента эта функция извлекает тег скрипта, который следует использовать для формирования во всех последующих операциях.

Тег скрипта обычно определяется scriptItemizeOpenType из входных символов. Если функция получает определенный тег скрипта, приложение должно передать его другим функциям без изменений. Однако если символы являются нейтральными (например, цифрами) и скрипт не может быть определен, приложение должно выбрать соответствующий тег скрипта, например, на основе шрифта и языка, связанного с текстом.

Важно Начиная с Windows 8. Чтобы поддерживать возможность запуска в Windows 7, модуль, использующий Uniscribe, должен указать Usp10.lib перед gdi32.lib в списке библиотек.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	usp10.h
Библиотека	Usp10.lib
DLL	Usp10.dll
Распространяемые компоненты	Usp10.dll версии 1.600 или более поздней в Windows XP