Função ScriptItemize (usp10.h)

Artigo
08/26/2023

Divide uma cadeia de caracteres Unicode em itens formatáveis individualmente.

Sintaxe

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

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 para conter 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] 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.

A função retornará E_INVALIDARG se pwcInChars estiver definido como NULL, cInChars for 0, pItems for definido como NULL ou cMaxItems< 2.

A função retornará E_OUTOFMEMORY se o valor de cMaxItems for insuficiente. Como em todos os casos de erro, nenhum item é totalmente processado e nenhuma parte da matriz de saída contém valores definidos. Se a função retornar E_OUTOFMEMORY, o aplicativo poderá chamá-la novamente com um buffer pItems maior.

Comentários

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 ScriptItemize. No entanto, ele não deve combinar vários itens em uma única execução. Posteriormente, ao medir ou renderizar, o aplicativo pode chamar ScriptShape para cada execução e deve passar a estrutura SCRIPT_ANALYSIS recuperada por ScriptItemize na estrutura SCRIPT_ITEM .

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 ScriptItemize. 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 ScriptItemize 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 ScriptItemize 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 de SCRIPT_ANALYSIS é referenciado em SCRIPT_ITEM enabled="1". 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	Iniba a formação árabe, ou seja, ligaturas e conexões cursivas, para formulários de apresentação árabe. 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 à medida que processa texto forte.

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 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	usp10.h
Biblioteca	Usp10.lib
DLL	Usp10.dll
Redistribuível	Internet Explorer 5 ou posterior no Windows Me/98/95