Compartilhar via


Função ScriptItemize (usp10.h)

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

Confira também

Exibindo texto com Uniscribe

SCRIPT_ANALYSIS

SCRIPT_CONTROL

SCRIPT_ITEM

SCRIPT_PROPERTIES

SCRIPT_STATE

ScriptItemizeOpenType

Scriptshape

Uniscribe

Funções Uniscribe