Función ScriptStringAnalyse (usp10.h)

Artículo
01/10/2024

Analiza una cadena de texto sin formato.

Sintaxis

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 del contexto del dispositivo. Si dwFlags se establece en SSA_GLYPHS, se requiere el identificador de contexto del dispositivo. Si dwFlags se establece en SSA_BREAK, el identificador de contexto del dispositivo es opcional. Si se proporciona el identificador de contexto del dispositivo, la función inspecciona la fuente actual en el contexto del dispositivo. Si la fuente actual es una fuente simbólica, la función trata la cadena de caracteres como un solo elemento de SCRIPT_UNDEFINED neutro.

[in] pString

Puntero a la cadena que se va a analizar. La cadena debe tener al menos un carácter. Puede ser una cadena Unicode o usar el juego de caracteres de una página de códigos ANSI de Windows, según lo especificado por el parámetro iCharset .

[in] cString

Longitud de la cadena que se va a analizar. La longitud se mide en caracteres para una cadena ANSI o en caracteres anchos para una cadena Unicode. La longitud debe ser de al menos 1.

[in] cGlyphs

Tamaño del búfer de glifos, en valores de WORD. Este tamaño es necesario. El tamaño recomendado es (1.5 * cString + 16).

[in] iCharset

Descriptor del juego de caracteres. Si la cadena de entrada es una cadena ANSI, este descriptor se establece en el identificador del juego de caracteres. Si la cadena es una cadena Unicode, este descriptor se establece en -1.

Se definen los siguientes identificadores de juego de caracteres:

[in] dwFlags

Marcas que indican el análisis necesario. Este parámetro puede tener uno de los valores enumerados en la tabla siguiente.

Valor	Significado
SSA_BREAK	Recuperar marcas de interrupción, es decir, caracteres y palabras se detiene.
SSA_CLIP	Recorte la cadena en iReqWidth.
SSA_DZWG	Proporcione glifos de representación para caracteres de control.
SSA_FALLBACK	Use fuentes de reserva.
SSA_FIT	Justifica la cadena en iReqWidth.
SSA_GCP	Recupere los glifos que faltan y pwLogClust con convenciones GetCharacterPlacement .
SSA_GLYPHS	Generar glifos, posiciones y atributos.
SSA_HIDEHOTKEY	Quite la primera "&" de la cadena mostrada.
SSA_HOTKEY	Reemplace "&" por subrayado en el punto de código posterior.
SSA_HOTKEYONLY	Mostrar solo subrayado. Es posible que se muestre el patrón de bits resultante, mediante una máscara XOR, para alternar la visibilidad del subrayado de tecla de acceso rápido sin alterar el texto.
SSA_LINK	Aplique la vinculación y asociación de fuentes de Asia Oriental al texto no complejo.
SSA_METAFILE	Escribir elementos con llamadas ExtTextOutW , no con glifos.
SSA_PASSWORD	Cadena de entrada duplicada que contiene un solo carácter cString times.
SSA_RTL	Use el nivel de inserción base 1.
SSA_TAB	Expanda pestañas.

[in] iReqWidth

Ancho necesario para ajustar o recortar.

[in, optional] psControl

Puntero a una estructura de SCRIPT_CONTROL . La aplicación puede establecer este parámetro en NULL para indicar que todos los miembros de SCRIPT_CONTROL están establecidos en 0.

[in, optional] psState

Puntero a una estructura de SCRIPT_STATE . La aplicación puede establecer este parámetro en NULL para indicar que todos los miembros de SCRIPT_STATE están establecidos en 0. Se omite el miembro uBidiLevel de SCRIPT_STATE . El valor usado se deriva de la marca SSA_RTL en combinación con el diseño del contexto del dispositivo.

[in, optional] piDx

Puntero a la matriz dx lógica solicitada.

[in, optional] pTabdef

Puntero a una estructura SCRIPT_TABDEF . Este valor solo es necesario si dwFlags está establecido en SSA_TAB.

[in] pbInClass

Puntero a un valor BYTE que indica las clasificaciones de caracteres GetCharacterPlacement .

[out] pssa

Puntero a un búfer en el que esta función recupera una estructura SCRIPT_STRING_ANALYSIS . Esta estructura se asigna dinámicamente cuando la función devuelve correctamente.

Valor devuelto

Devuelve S_OK si se ejecuta correctamente. La función devuelve un valor HRESULT distinto de cero si no se realiza correctamente.

Entre las devoluciones de error se incluyen:

E_INVALIDARG. Se encuentra un parámetro no válido.
USP_E_SCRIPT_NOT_IN_FONT. SSA_FALLBACK no se ha especificado o falta una fuente de reserva estándar.

La función también puede devolver un error del sistema convertido a un tipo HRESULT. Un ejemplo es un error devuelto debido a la falta de memoria o a una llamada GDI mediante el contexto del dispositivo.

Comentarios

El uso de esta función es el primer paso para controlar las cadenas de texto sin formato. Esta cadena tiene solo una fuente, un estilo, un tamaño, un color, etc. ScriptStringAnalyse asigna búferes temporales para análisis de elementos, glifos, anchos avanzados y similares. A continuación, ejecuta automáticamente ScriptItemize, ScriptShape, ScriptPlace y ScriptBreak. Los resultados están disponibles a través de todas las demás funciones scriptString* .

Si la devolución se realiza correctamente de esta función, pssa indica una estructura asignada dinámicamente que la aplicación puede pasar sucesivamente a las demás funciones ScriptString* . La aplicación debe liberar en última instancia la estructura mediante una llamada a ScriptStringFree.

Aunque la funcionalidad de ScriptStringAnalyse se puede implementar mediante llamadas directas a otras funciones, el uso de la propia función reduce drásticamente la cantidad de código necesario en la aplicación para el control de texto sin formato.

Importante A partir de Windows 8: para mantener la capacidad de ejecutarse en Windows 7, un módulo que usa Uniscribe debe especificar Usp10.lib antes de gdi32.lib en su lista de bibliotecas.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	usp10.h
Library	Usp10.lib
Archivo DLL	Usp10.dll
Redistribuible	Internet Explorer 5 o posterior en Windows Me/98/95