Função ScriptStringAnalyse (usp10.h)

Artigo
03/03/2024

Analisa uma cadeia de caracteres de texto sem formatação.

Sintaxe

HRESULT ScriptStringAnalyse(
  [in]           HDC                    hdc,
  [in]           const void             *pString,
  [in]           int                    cString,
  [in]           int                    cGlyphs,
  [in]           int                    iCharset,
  [in]           DWORD                  dwFlags,
  [in]           int                    iReqWidth,
  [in, optional] SCRIPT_CONTROL         *psControl,
  [in, optional] SCRIPT_STATE           *psState,
  [in, optional] const int              *piDx,
  [in, optional] SCRIPT_TABDEF          *pTabdef,
  [in]           const BYTE             *pbInClass,
  [out]          SCRIPT_STRING_ANALYSIS *pssa
);

Parâmetros

[in] hdc

Identificador para o contexto do dispositivo. Se dwFlags estiver definido como SSA_GLYPHS, o identificador de contexto do dispositivo será necessário. Se dwFlags estiver definido como SSA_BREAK, o identificador de contexto do dispositivo será opcional. Se o identificador de contexto do dispositivo for fornecido, a função inspecionará a fonte atual no contexto do dispositivo. Se a fonte atual for uma fonte simbólica, a função tratará a cadeia de caracteres como um único item neutro SCRIPT_UNDEFINED.

[in] pString

Ponteiro para a cadeia de caracteres a ser analisada. A cadeia de caracteres deve ter pelo menos um caractere. Pode ser uma cadeia de caracteres Unicode ou usar o conjunto de caracteres de uma página de código ANSI do Windows, conforme especificado pelo parâmetro iCharset .

[in] cString

Comprimento da cadeia de caracteres a ser analisada. O comprimento é medido em caracteres para uma cadeia de caracteres ANSI ou em caracteres largos para uma cadeia de caracteres Unicode. O comprimento deve ser pelo menos 1.

[in] cGlyphs

Tamanho do buffer de glifo, em valores word. Esse tamanho é necessário. O tamanho recomendado é (1.5 * cString + 16).

[in] iCharset

Descritor de conjunto de caracteres. Se a cadeia de caracteres de entrada for uma cadeia de caracteres ANSI, esse descritor será definido como o identificador do conjunto de caracteres. Se a cadeia de caracteres for uma cadeia de caracteres Unicode, esse descritor será definido como -1.

Os seguintes identificadores de conjunto de caracteres são definidos:

[in] dwFlags

Sinalizadores que indicam a análise necessária. Esse parâmetro pode ter um dos valores listados na tabela a seguir.

Valor	Significado
SSA_BREAK	Recupere sinalizadores de interrupção, ou seja, paradas de caracteres e palavras.
SSA_CLIP	Recorte a cadeia de caracteres em iReqWidth.
SSA_DZWG	Forneça glifos de representação para caracteres de controle.
SSA_FALLBACK	Use fontes de fallback.
SSA_FIT	Justifique a cadeia de caracteres para iReqWidth.
SSA_GCP	Recupere glifos ausentes e pwLogClust com convenções GetCharacterPlacement .
SSA_GLYPHS	Gerar glifos, posições e atributos.
SSA_HIDEHOTKEY	Remova o primeiro "&" da cadeia de caracteres exibida.
SSA_HOTKEY	Substitua "&" por sublinhado no ponto de código subsequente.
SSA_HOTKEYONLY	Exibir somente sublinhado. O padrão de bit resultante pode ser exibido, usando uma máscara XOR, para alternar a visibilidade do sublinhado de tecla de atalho sem perturbar o texto.
SSA_LINK	Aplique vinculação e associação de fontes do Leste Asiático a textos não compatíveis.
SSA_METAFILE	Escreva itens com chamadas ExtTextOutW , não com glifos.
SSA_PASSWORD	Cadeia de caracteres de entrada duplicada que contém um único caractere cString vezes.
SSA_RTL	Use o nível de inserção base 1.
SSA_TAB	Expanda guias.

[in] iReqWidth

Largura necessária para ajustar ou recortar.

[in, optional] psControl

Ponteiro para uma estrutura SCRIPT_CONTROL . O aplicativo pode definir esse parâmetro como NULL para indicar que todos os membros SCRIPT_CONTROL estão definidos como 0.

[in, optional] psState

Ponteiro para uma estrutura SCRIPT_STATE . O aplicativo pode definir esse parâmetro como NULL para indicar que todos os membros SCRIPT_STATE estão definidos como 0. O membro uBidiLevel de SCRIPT_STATE é ignorado. O valor usado é derivado do sinalizador SSA_RTL em combinação com o layout do contexto do dispositivo.

[in, optional] piDx

Ponteiro para a matriz dx lógica solicitada.

[in, optional] pTabdef

Ponteiro para uma estrutura SCRIPT_TABDEF . Esse valor só será necessário se dwFlags estiver definido como SSA_TAB.

[in] pbInClass

Ponteiro para um valor BYTE que indica classificações de caracteres GetCharacterPlacement .

[out] pssa

Ponteiro para um buffer no qual essa função recupera uma estrutura SCRIPT_STRING_ANALYSIS . Essa estrutura é alocada dinamicamente no retorno bem-sucedido da função.

Retornar valor

Retorna S_OK se tiver êxito. A função retornará um valor HRESULT diferente de zero se não for bem-sucedida.

Os retornos de erro incluem:

E_INVALIDARG. Um parâmetro inválido é encontrado.
USP_E_SCRIPT_NOT_IN_FONT. SSA_FALLBACK não foi especificado ou uma fonte de fallback padrão está ausente.

A função também pode retornar um erro do sistema convertido em um tipo HRESULT. Um exemplo é um erro retornado devido à falta de memória ou a uma chamada GDI usando o contexto do dispositivo.

Comentários

O uso dessa função é a primeira etapa no tratamento de cadeias de caracteres de texto sem formatação. Essa cadeia de caracteres tem apenas uma fonte, um estilo, um tamanho, uma cor e assim por diante. ScriptStringAnalyse aloca buffers temporários para análises de itens, glifos, larguras avançadas e similares. Em seguida, ele executa automaticamente ScriptItemize, ScriptShape, ScriptPlace e ScriptBreak. Os resultados estão disponíveis por meio de todas as outras funções ScriptString* .

No retorno bem-sucedido dessa função, pssa indica uma estrutura alocada dinamicamente que o aplicativo pode passar sucessivamente para as outras funções ScriptString* . Em última análise, o aplicativo deve liberar a estrutura chamando ScriptStringFree.

Embora a funcionalidade de ScriptStringAnalyse possa ser implementada por chamadas diretas para outras funções, o uso da função em si reduz drasticamente a quantidade de código necessária no aplicativo para tratamento de texto sem formatação.

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