Función ScriptItemizeOpenType (usp10.h)

Artículo
08/26/2023

Divide una cadena Unicode en elementos con forma individual y proporciona una matriz de etiquetas de características para cada elemento con forma para el procesamiento de OpenType.

Sintaxis

HRESULT ScriptItemizeOpenType(
  [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]          OPENTYPE_TAG         *pScriptTags,
  [out]          int                  *pcItems
);

Parámetros

[in] pwcInChars

Puntero a una cadena Unicode que se va a desglosar.

[in] cInChars

Número de caracteres de pwcInChars que se van a desglosar.

[in] cMaxItems

Número máximo de estructuras de SCRIPT_ITEM que definen los elementos que se van a procesar.

[in, optional] psControl

Puntero a una estructura de SCRIPT_CONTROL que indica el tipo de itemización que se va a realizar.

Como alternativa, la aplicación puede establecer este parámetro en NULL si no se necesitan propiedades de SCRIPT_CONTROL . Para obtener más información, vea la sección Comentarios.

[in, optional] psState

Puntero a una estructura de SCRIPT_STATE que indica el estado inicial del algoritmo bidireccional.

Como alternativa, la aplicación puede establecer este parámetro en NULL si el estado del script no es necesario. Para obtener más información, vea la sección Comentarios.

[out] pItems

Puntero a un búfer en el que la función recupera SCRIPT_ITEM estructuras que representan los elementos que se han procesado. El búfer debe tener (cMaxItems + 1) * sizeof(SCRIPT_ITEM) una longitud de bytes. No es válido llamar a esta función con un búfer que controla menos de dos estructuras de SCRIPT_ITEM . La función siempre agrega un elemento de terminal a la matriz de análisis de elementos para que la longitud del elemento con índice de base cero "i" esté siempre disponible como:

pItems[i+1].iCharPos - pItems[i].iCharPos;

[out] pScriptTags

Puntero a un búfer en el que la función recupera una matriz de estructuras de OPENTYPE_TAG que representan etiquetas de script. El búfer debe tener cMaxItems * sizeof(OPENTYPE_TAG) una longitud de bytes.

Nota Cuando todos los caracteres de un elemento son neutros, el valor de este parámetro es SCRIPT_TAG_UNKNOWN (0x00000000). Esto puede ocurrir, por ejemplo, si un elemento consta completamente de puntuación.

[out] pcItems

Puntero al número de estructuras de SCRIPT_ITEM procesadas.

Valor devuelto

Si la operación se realiza correctamente, devuelve 0. La función devuelve un valor HRESULT distinto de cero si no se realiza correctamente. En todos los casos de error, ningún elemento se procesa por completo y ninguna parte de la salida contiene valores definidos. La aplicación puede probar el valor devuelto con las macros SUCCEEDED y FAILED .

La función devuelve E_OUTOFMEMORY si el tamaño indicado por cMaxItems es demasiado pequeño. La aplicación puede intentar llamar a la función de nuevo con un búfer mayor.

La función devuelve E_INVALIDARG si se producen una o varias de las condiciones siguientes:

pwcInChars se establece en NULL.
cInChars es 0
pItems se establece en NULL.
pScriptTags se establece en NULL.
cMaxItems< 2

Comentarios

Se prefiere ScriptItemizeOpenType sobre la función ScriptItemize anterior. Una ventaja de ScriptItemizeOpenType es la disponibilidad de etiquetas de características para cada elemento con forma.

Vea Mostrar texto con Uniscribe para obtener una explicación del contexto en el que normalmente se llama a esta función.

La función delimita los elementos mediante un cambio de motor de forma o un cambio de dirección.

La aplicación puede crear varios intervalos o ejecuciones que se encuentran completamente dentro de un solo elemento, desde cada estructura de SCRIPT_ITEM recuperada por ScriptItemizeOpenType. Sin embargo, no debe combinar varios elementos en una sola ejecución. Al medir o representar, la aplicación puede llamar a ScriptShapeOpenType para cada ejecución y debe pasar la estructura de SCRIPT_ANALYSIS correspondiente en la estructura de SCRIPT_ITEM recuperada por ScriptItemizeOpenType.

Si el texto controlado por una aplicación puede incluir cualquier contenido de derecha a izquierda, la aplicación usa los parámetros psControl y psState para llamar a ScriptItemizeOpenType. Sin embargo, la aplicación no tiene que hacerlo y puede controlar el propio texto bidireccional en lugar de depender de Uniscribe para hacerlo. Los parámetros psControl y psState son útiles en algunos escenarios estrictamente de izquierda a derecha, por ejemplo, cuando el miembro fLinkStringBefore de SCRIPT_CONTROL no es específico de scripts de derecha a izquierda. La aplicación establece psControl y psState en NULL para que ScriptItemizeOpenType interrumpa la cadena Unicode únicamente por código de carácter.

La aplicación puede establecer todos los parámetros en valores que no son NULL para que la función realice un análisis bidireccional Unicode completo. Para permitir un análisis bidireccional Unicode correcto, la estructura de SCRIPT_STATE debe inicializarse según el orden de lectura al principio del párrafo y se debe pasar el párrafo completo. En concreto, el miembro uBidiLevel debe inicializarse en 0 para de izquierda a derecha y 1 para derecha a izquierda.

En SCRIPT_ITEM se hace referencia al miembro fRTL de SCRIPT_ANALYSIS. ScriptGetProperties recupera el miembro fNumeric de SCRIPT_PROPERTIES. Estos miembros juntos proporcionan la misma clasificación que el miembro lpClass de GCP_RESULTS, al que hace referencia lpResults en GetCharacterPlacement.

Los dígitos europeos U+0030 a U+0039 se pueden representar como dígitos nacionales, como se muestra en la tabla siguiente.

SCRIPT_STATE.fDigitSubstitute	SCRIPT_CONTROL.fContextDigits	Formas de dígito mostradas para Unicode U+0030 a U+0039
FALSE	Any	Dígitos europeos
TRUE	FALSE	Como se especifica en el miembro uDefaultLanguage de SCRIPT_CONTROL.
TRUE	TRUE	Como texto seguro anterior, el valor predeterminado es el miembro uDefaultLanguage de SCRIPT_CONTROL.

En el modo de dígito de contexto, se produce una de las siguientes acciones:

Si el script especificado por uDefaultLanguage está en la misma dirección que la salida, todos los dígitos encontrados antes de las primeras letras se representan en el idioma indicado por uDefaultLanguage.
Si el script especificado por uDefaultLanguage está en la dirección opuesta de la salida, todos los dígitos encontrados antes de las primeras letras se representan en dígitos europeos.

Por ejemplo, si uDefaultLanguage indica LANG_ARABIC, los dígitos iniciales están en Arabic-Indic en una inserción de derecha a izquierda. Sin embargo, están en dígitos europeos en una inserción de izquierda a derecha.

Para obtener más información, vea Formas de dígitos.

Los caracteres y definiciones de control Unicode, y sus efectos en SCRIPT_STATE miembros, se proporcionan en la tabla siguiente. Para obtener más información sobre los caracteres de control Unicode, vea El estándar Unicode.

Caracteres de control Unicode	Significado	Efecto en SCRIPT_STATE
NADS	Invalide los dígitos europeos (NODS) con formas de dígitos nacionales.	Establezca fDigitSubstitute.
CABECEA	Use formas nominales de dígitos, también conocidas como dígitos europeos. Consulte NADS.	Borrar fDigitSubstitute.
CULO	Active el intercambio de pares simétricos, por ejemplo, paréntesis. Para estos caracteres, a la izquierda y a la derecha se interpretan como apertura y cierre. Este es el valor predeterminado. Consulte ISS.	Borre fInhibitSymSwap.
ISS	Inhiba el intercambio de pares simétricos. Consulte ASS.	Establezca fInhibitSymSwap.
AAFS	Active la forma de formulario árabe para los formularios de presentación en árabe. Consulte IAFS.	Establezca fCharShape.
IAFS	Inhiba la forma en árabe, es decir, ligaduras y conexiones cursivas, para las formas de presentación en árabe. Los caracteres árabes nominales no se ven afectados. Este es el valor predeterminado. Consulte AAFS.	Borra fCharShape.

El miembro fArabicNumContext de SCRIPT_STATE admite la visualización contextual de números en el texto del script árabe. Indica si los dígitos se representan mediante formas nativas de dígitos de script árabe o dígitos europeos. Al principio de un párrafo, este miembro normalmente debe inicializarse en TRUE para una configuración regional árabe o FALSE para cualquier otra configuración regional. La función actualiza el script cuando procesa texto seguro.

El parámetro de salida pScriptTags indica una matriz con entradas paralelas a los elementos. Para cada elemento, esta función recupera una etiqueta de script que se debe usar para dar forma a todas las operaciones posteriores.

Normalmente, una etiqueta de script viene determinada por ScriptItemizeOpenType a partir de caracteres de entrada. Si la función recupera una etiqueta de script específica, la aplicación debe pasarla a otras funciones sin cambiar. Sin embargo, cuando los caracteres son neutros (por ejemplo, dígitos) y no se puede determinar el script, la aplicación debe elegir una etiqueta de script adecuada, por ejemplo, en función de la fuente y el idioma asociados al texto.

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 Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	usp10.h
Library	Usp10.lib
Archivo DLL	Usp10.dll
Redistribuible	Usp10.dll versión 1.600 o posterior en Windows XP