Função ScriptItemizeOpenType (usp10.h)

Artigo
08/26/2023

Divide uma cadeia de caracteres Unicode em itens formatáveis individualmente e fornece uma matriz de marcas de recurso para cada item shapeable para processamento OpenType.

Sintaxe

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
);

Parâmetros

[in] pwcInChars

Ponteiro para uma cadeia de caracteres Unicode a ser itemizada.

[in] cInChars

Número de caracteres em pwcInChars a serem itemizados.

[in] cMaxItems

Número máximo de estruturas de SCRIPT_ITEM definindo itens a serem processados.

[in, optional] psControl

Ponteiro para uma estrutura SCRIPT_CONTROL indicando o tipo de itemização a ser executada.

Como alternativa, o aplicativo poderá definir esse parâmetro como NULL se nenhuma SCRIPT_CONTROL propriedades for necessária. Para obter mais informações, consulte a seção Comentários.

[in, optional] psState

Ponteiro para uma estrutura SCRIPT_STATE indicando o estado inicial do algoritmo bidirecional.

Como alternativa, o aplicativo poderá definir esse parâmetro como NULL se o estado do script não for necessário. Para obter mais informações, consulte a seção Comentários.

[out] pItems

Ponteiro para um buffer no qual a função recupera SCRIPT_ITEM estruturas que representam os itens que foram processados. O buffer deve ter (cMaxItems + 1) * sizeof(SCRIPT_ITEM) comprimento de bytes. É inválido chamar essa função com um buffer que manipula menos de duas estruturas SCRIPT_ITEM . A função sempre adiciona um item de terminal à matriz de análise de itens para que o comprimento do item com índice baseado em zero "i" esteja sempre disponível como:

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

[out] pScriptTags

Ponteiro para um buffer no qual a função recupera uma matriz de estruturas OPENTYPE_TAG que representam marcas de script. O buffer deve ter cMaxItems * sizeof(OPENTYPE_TAG) comprimento de bytes.

Nota Quando todos os caracteres em um item são neutros, o valor desse parâmetro é SCRIPT_TAG_UNKNOWN (0x00000000). Isso pode acontecer, por exemplo, se um item consistir inteiramente em pontuação.

[out] pcItems

Ponteiro para o número de estruturas de SCRIPT_ITEM processadas.

Retornar valor

Retorna 0 se for bem-sucedido. A função retornará um valor HRESULT diferente de zero se não for bem-sucedida. Em todos os casos de erro, nenhum item é totalmente processado e nenhuma parte da saída contém valores definidos. O aplicativo pode testar o valor retornado com as macros SUCCEEDED e FAILED .

A função retornará E_OUTOFMEMORY se o tamanho indicado por cMaxItems for muito pequeno. O aplicativo pode tentar chamar a função novamente com um buffer maior.

A função retornará E_INVALIDARG se uma ou mais das seguintes condições ocorrerem:

pwcInChars está definido como NULL
cInChars é 0
pItems é definido como NULL
pScriptTags é definido como NULL
cMaxItems< 2

Comentários

ScriptItemizeOpenType é preferencial em vez da função ScriptItemize mais antiga. Uma vantagem de ScriptItemizeOpenType é a disponibilidade de marcas de recurso para cada item shapeable.

Consulte Exibindo texto com Uniscribe para ver uma discussão sobre o contexto no qual essa função normalmente é chamada.

A função delimita itens por uma alteração do mecanismo de formatação ou uma alteração de direção.

O aplicativo pode criar vários intervalos ou execuções que se enquadram inteiramente em um único item, de cada estrutura SCRIPT_ITEM recuperada por ScriptItemizeOpenType. No entanto, ele não deve combinar vários itens em uma única execução. Ao medir ou renderizar, o aplicativo pode chamar ScriptShapeOpenType para cada execução e deve passar a estrutura de SCRIPT_ANALYSIS correspondente na estrutura SCRIPT_ITEM recuperada por ScriptItemizeOpenType.

Se o texto manipulado por um aplicativo puder incluir qualquer conteúdo da direita para a esquerda, o aplicativo usará os parâmetros psControl e psState na chamada de ScriptItemizeOpenType. No entanto, o aplicativo não precisa fazer isso e pode lidar com o texto bidirecional em si, em vez de depender de Uniscribe para fazer isso. Os parâmetros psControl e psState são úteis em alguns cenários estritamente da esquerda para a direita, por exemplo, quando o membro fLinkStringBefore de SCRIPT_CONTROL não é específico para scripts da direita para a esquerda. O aplicativo define psControl e psState como NULL para que ScriptItemizeOpenType interrompa a cadeia de caracteres Unicode puramente por código de caractere.

O aplicativo pode definir todos os parâmetros como valores não NULL para que a função execute uma análise bidirecional Unicode completa. Para permitir uma análise bidirecional Unicode correta, a estrutura de SCRIPT_STATE deve ser inicializada de acordo com a ordem de leitura no início do parágrafo e ScriptItemizeOpenType deve ser passado o parágrafo inteiro. Em particular, o membro uBidiLevel deve ser inicializado como 0 para da esquerda para a direita e 1 para a direita para a esquerda.

O membro fRTL do SCRIPT_ANALYSIS é referenciado em SCRIPT_ITEM. O membro fNumeric de SCRIPT_PROPERTIES é recuperado por ScriptGetProperties. Esses membros juntos fornecem a mesma classificação que o membro lpClass de GCP_RESULTS, referenciado por lpResults em GetCharacterPlacement.

Os dígitos europeus U+0030 a U+0039 podem ser renderizados como dígitos nacionais, conforme mostrado na tabela a seguir.

SCRIPT_STATE.fDigitSubstitute	SCRIPT_CONTROL.fContextDigits	Formas de dígito exibidas para Unicode U+0030 a U+0039
FALSE	Qualquer	Dígitos europeus
TRUE	FALSE	Conforme especificado no membro uDefaultLanguage de SCRIPT_CONTROL.
TRUE	TRUE	Como texto forte anterior, o padrão é uDefaultLanguage membro de SCRIPT_CONTROL.

No modo de dígito de contexto, ocorre uma das seguintes ações:

Se o script especificado por uDefaultLanguage estiver na mesma direção que a saída, todos os dígitos encontrados antes das primeiras letras serão renderizados no idioma indicado por uDefaultLanguage.
Se o script especificado por uDefaultLanguage estiver na direção oposta da saída, todos os dígitos encontrados antes das primeiras letras serão renderizados em dígitos europeus.

Por exemplo, se uDefaultLanguage indicar LANG_ARABIC, os dígitos iniciais estarão em Arabic-Indic em uma inserção da direita para a esquerda. No entanto, eles estão em dígitos europeus em uma inserção da esquerda para a direita.

Para obter mais informações, consulte Digit Shapes.

Os caracteres e definições de controle Unicode e seus efeitos em membros SCRIPT_STATE são fornecidos na tabela a seguir. Para obter mais informações sobre caracteres de controle Unicode, consulte o Padrão Unicode.

Caracteres de controle Unicode	Significado	Efeito no SCRIPT_STATE
NADS	Substitua os dígitos europeus (NODS) por formas de dígitos nacionais.	Defina fDigitSubstitute.
ACENA	Use formas de dígito nominal, também conhecidas como dígitos europeus. Consulte NADS.	Limpe fDigitSubstitute.
BUNDA	Ativar a troca de pares simétricos, por exemplo, parênteses. Para esses caracteres, esquerda e direita são interpretadas como abertura e fechamento. Esse é o padrão. Confira ISS.	Limpe fInhibitSymSwap.
ISS	Inibir a troca de pares simétricos. Consulte ASS.	Defina fInhibitSymSwap.
AAFS	Ativar a formação de formulário árabe para formulários de apresentação em árabe. Consulte IAFS.	Defina fCharShape.
IAFS	Inibir a forma árabe modelando, ou seja, ligaturas e conexões cursivas, para formulários de apresentação árabes. Caracteres árabes nominais não são afetados. Esse é o padrão. Consulte AAFS.	Limpar fCharShape.

O membro fArabicNumContext do SCRIPT_STATE dá suporte à exibição contextual de numerais no texto de script árabe. Indica se os dígitos são renderizados usando formas de dígito de script árabe nativo ou dígitos europeus. No início de um parágrafo, esse membro normalmente deve ser inicializado como TRUE para uma localidade árabe ou FALSE para qualquer outra localidade. A função atualiza o estado do script enquanto processa texto forte.

O parâmetro de saída pScriptTags indica uma matriz com entradas paralelas aos itens. Para cada item, essa função recupera uma marca de script que deve ser usada para modelagem em todas as operações subsequentes.

Uma marca de script geralmente é determinada por ScriptItemizeOpenType a partir de caracteres de entrada. Se a função recuperar uma marca de script específica, o aplicativo deverá passá-la para outras funções sem alteração. No entanto, quando os caracteres são neutros (por exemplo, dígitos) e o script não pode ser determinado, o aplicativo deve escolher uma marca de script apropriada, por exemplo, com base na fonte e no idioma associados ao texto.

Importante Começando com Windows 8: para manter a capacidade de execução no Windows 7, um módulo que usa Uniscribe deve especificar Usp10.lib antes de gdi32.lib em sua lista de bibliotecas.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	usp10.h
Biblioteca	Usp10.lib
DLL	Usp10.dll
Redistribuível	Usp10.dll versão 1.600 ou superior no Windows XP