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

Статья
08/26/2023

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

Синтаксис

HRESULT ScriptItemize(
  [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]          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] pcItems

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

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

Возвращает 0 в случае успеха. Функция возвращает ненулевое значение HRESULT, если не удалось.

Функция возвращает E_INVALIDARG, если для pwcInChars задано значение NULL, cInChars — 0, pItems — NULL или cMaxItems< 2.

Функция возвращает E_OUTOFMEMORY, если значения cMaxItems недостаточно. Как и во всех случаях ошибок, ни одна из элементов не обрабатывается полностью, и ни одна часть выходного массива не содержит определенных значений. Если функция возвращает E_OUTOFMEMORY, приложение может вызвать его снова с большим буфером pItems .

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

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

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

На элемент fRTLSCRIPT_ANALYSIS ссылается SCRIPT_ITEM enabled="1". Элемент 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	Препятствуют формированию арабской формы, т. е. лигатур и крививных связей, для арабских форм представления. Номинальные арабские символы не затрагиваются. Это значение по умолчанию. См. раздел AAFS.	Снимите флажок fCharShape.

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

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	usp10.h
Библиотека	Usp10.lib
DLL	Usp10.dll
Распространяемые компоненты	Internet Обозреватель 5 или более поздней версии в Windows Me/98/95