Função ScriptShape (usp10.h)
Gera glifos e atributos visuais para uma execução Unicode.
Sintaxe
HRESULT ScriptShape(
[in] HDC hdc,
[in, out] SCRIPT_CACHE *psc,
[in] const WCHAR *pwcChars,
[in] int cChars,
[in] int cMaxGlyphs,
[in, out] SCRIPT_ANALYSIS *psa,
[out] WORD *pwOutGlyphs,
[out] WORD *pwLogClust,
[out] SCRIPT_VISATTR *psva,
[out] int *pcGlyphs
);
Parâmetros
[in] hdc
Opcional. Identificador para o contexto do dispositivo. Para obter mais informações, consulte Cache.
[in, out] psc
Ponteiro para uma estrutura SCRIPT_CACHE que identifica o cache de script.
[in] pwcChars
Ponteiro para uma matriz de caracteres Unicode que define a execução.
[in] cChars
Número de caracteres na execução Unicode.
[in] cMaxGlyphs
Número máximo de glifos a serem gerados e o comprimento de pwOutGlyphs. Um valor razoável é (1.5 * cChars + 16), mas esse valor pode ser insuficiente em algumas circunstâncias. Para obter mais informações, consulte a seção Comentários.
[in, out] psa
Ponteiro para a estrutura de SCRIPT_ANALYSIS para a execução, contendo os resultados de uma chamada anterior para ScriptItemize.
[out] pwOutGlyphs
Ponteiro para um buffer no qual essa função recupera uma matriz de glifos com tamanho, conforme indicado por cMaxGlyphs.
[out] pwLogClust
Ponteiro para um buffer no qual essa função recupera uma matriz de informações de cluster lógico. Cada elemento de matriz corresponde a um caractere na matriz de caracteres Unicode; portanto, essa matriz tem o número de elementos indicados por cChars. O valor de cada elemento é o deslocamento do primeiro glifo na execução para o primeiro glifo no cluster que contém o caractere correspondente. Observe que, quando o membro fRTL é definido como TRUE na estrutura SCRIPT_ANALYSIS , os elementos diminuem à medida que a matriz é lida.
[out] psva
Ponteiro para um buffer no qual essa função recupera uma matriz de estruturas SCRIPT_VISATTR que contêm informações de atributo visual. Como cada glifo tem apenas um atributo visual, essa matriz tem o número de elementos indicados por cMaxGlyphs.
[out] pcGlyphs
Ponteiro para o local em que essa função recupera o número de glifos indicados em pwOutGlyphs.
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, o conteúdo de todos os parâmetros de saída é indefinido.
Os retornos de erro incluem:
- E_OUTOFMEMORY. O comprimento do buffer de saída indicado por cMaxGlyphs é insuficiente.
- E_PENDING. O cache de script especificado pelo parâmetro psc não contém informações suficientes para moldar a cadeia de caracteres e o contexto do dispositivo foi passado como NULL para que a função não possa concluir o processo de formatação. O aplicativo deve configurar um contexto de dispositivo correto para a execução e chamar essa função novamente com o valor apropriado em hdc e com todos os outros parâmetros da mesma forma.
- USP_E_SCRIPT_NOT_IN_FONT. A fonte correspondente ao contexto do dispositivo não dá suporte ao script exigido pela execução indicada por pwcChars. O aplicativo deve escolher outra fonte, usando ScriptGetCMap ou outra função para selecionar a fonte.
Comentários
Consulte Exibindo texto com Uniscribe para ver uma discussão sobre o contexto no qual essa função normalmente é chamada.
Se essa função retornar E_OUTOFMEMORY, o aplicativo poderá chamar ScriptShape repetidamente, com buffers de saída sucessivamente maiores, até que um buffer grande o suficiente seja fornecido. O número de glifos gerados por um ponto de código varia de acordo com o script e a fonte. Para um script simples, um ponto de código Unicode pode gerar um único glifo. No entanto, uma fonte de script complexa pode construir caracteres de componentes e, portanto, gerar várias vezes mais glifos do que caracteres. Além disso, há casos especiais, como representações de caractere inválidas, em que glifos extras são adicionados para representar a sequência inválida. Portanto, uma estimativa razoável para o tamanho do buffer indicado por pwOutGlyphs é 1,5 vezes o comprimento do buffer de caracteres, além de 16 glifos adicionais para casos raros, por exemplo, representação de sequência inválida.
Essa função pode definir o membro fNoGlyphIndex da estrutura SCRIPT_ANALYSIS se a fonte ou o sistema operacional não puder dar suporte a índices de glifo.
O aplicativo pode chamar ScriptShape para determinar se uma fonte dá suporte aos caracteres em uma determinada cadeia de caracteres. Se a função retornar S_OK, o aplicativo deverá marcar a saída para glifos ausentes. Se fLogicalOrder for definido como TRUE na estrutura SCRIPT_ANALYSIS , a função sempre gerará glifos na mesma ordem que os caracteres Unicode originais. Se fLogicalOrder for definido como FALSE, a função gerará itens da direita para a esquerda na ordem inversa para que ScriptTextOut não precise revertê-los antes de chamar ExtTextOut.
Se o membro eScript do SCRIPT_ANALYSIS estiver definido como SCRIPT_UNDEFINED, a formatação será desabilitada. Nesse caso, ScriptShape exibe o glifo que está na tabela cmap de fonte. Se nenhum glifo estiver na tabela, a função indicará que os glifos estão ausentes.
O ScriptShape sequencia clusters uniformemente dentro da execução e sequencia glifos uniformemente dentro de um cluster. Ele usa o valor do membro fRTL de SCRIPT_ANALYSIS, de ScriptItemize, para identificar o sequenciamento como da esquerda para a direita ou da direita para a esquerda.
Exemplos
O exemplo a seguir mostra como ScriptShape gera uma matriz de cluster lógico (pwLogClust) de uma matriz de caracteres (pwcChars) e uma matriz de glifo (pwOutGlyphs). A execução tem quatro clusters.
- Primeiro cluster: um caractere representado por um glifo
- Segundo cluster: um caractere representado por três glifos
- Terceiro cluster: três caracteres representados por um glifo
- Quarto cluster: dois caracteres representados por três glifos
- | c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |
- | c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |
- | 0 | 1 | 4 4 4 | 5 5 |
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 |