Fonction ScriptItemizeOpenType (usp10.h)

Article
08/26/2023

Décompose une chaîne Unicode en éléments pouvant être mis en forme individuellement et fournit un tableau de balises de fonctionnalité pour chaque élément pouvant être mis en forme pour le traitement OpenType.

Syntaxe

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
);

Paramètres

[in] pwcInChars

Pointeur vers une chaîne Unicode à itemize.

[in] cInChars

Nombre de caractères dans pwcInChars à itemiser.

[in] cMaxItems

Nombre maximal de structures SCRIPT_ITEM définissant des éléments à traiter.

[in, optional] psControl

Pointeur vers une structure de SCRIPT_CONTROL indiquant le type d’élément à effectuer.

L’application peut également définir ce paramètre sur NULL si aucune propriété SCRIPT_CONTROL n’est nécessaire. Pour plus d'informations, consultez la section Notes.

[in, optional] psState

Pointeur vers une structure SCRIPT_STATE indiquant l’état initial de l’algorithme bidirectionnel.

L’application peut également définir ce paramètre sur NULL si l’état du script n’est pas nécessaire. Pour plus d'informations, consultez la section Notes.

[out] pItems

Pointeur vers une mémoire tampon dans laquelle la fonction récupère SCRIPT_ITEM structures représentant les éléments qui ont été traités. La mémoire tampon doit être (cMaxItems + 1) * sizeof(SCRIPT_ITEM) d’une longueur d’octets. Il n’est pas valide d’appeler cette fonction avec une mémoire tampon qui gère moins de deux structures SCRIPT_ITEM . La fonction ajoute toujours un élément de terminal au tableau d’analyse d’élément afin que la longueur de l’élément avec l’index de base zéro « i » soit toujours disponible comme suit :

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

[out] pScriptTags

Pointeur vers une mémoire tampon dans laquelle la fonction récupère un tableau de structures OPENTYPE_TAG représentant des balises de script. La mémoire tampon doit être cMaxItems * sizeof(OPENTYPE_TAG) d’une longueur d’octets.

Note Lorsque tous les caractères d’un élément sont neutres, la valeur de ce paramètre est SCRIPT_TAG_UNKNOWN (0x00000000). Cela peut se produire, par exemple, si un élément se compose entièrement de ponctuation.

[out] pcItems

Pointeur vers le nombre de structures SCRIPT_ITEM traitées.

Valeur retournée

Retourne 0 en cas de réussite. La fonction retourne une valeur HRESULT différente de zéro si elle ne réussit pas. Dans tous les cas d’erreur, aucun élément n’est entièrement traité et aucune partie de la sortie ne contient de valeurs définies. L’application peut tester la valeur de retour avec les macros SUCCEEDED et FAILED .

La fonction retourne E_OUTOFMEMORY si la taille indiquée par cMaxItems est trop petite. L’application peut réessayer d’appeler la fonction avec une mémoire tampon plus grande.

La fonction retourne E_INVALIDARG si une ou plusieurs des conditions suivantes se produisent :

pwcInChars a la valeur NULL
cInChars est 0
pItems a la valeur NULL
pScriptTags a la valeur NULL
cMaxItems< 2

Remarques

ScriptItemizeOpenType est préféré à l’ancienne fonction ScriptItemize . L’un des avantages de ScriptItemizeOpenType est la disponibilité des balises de fonctionnalité pour chaque élément en forme.

Pour plus d’informations sur le contexte dans lequel cette fonction est normalement appelée, consultez Affichage de texte avec Uniscribe .

La fonction délimite les éléments par un changement de moteur de mise en forme ou par un changement de direction.

L’application peut créer plusieurs plages, ou des exécutions qui s’inscrivent entièrement dans un seul élément, à partir de chaque structure SCRIPT_ITEM récupérée par ScriptItemizeOpenType. Toutefois, il ne doit pas combiner plusieurs éléments en une seule exécution. Lors de la mesure ou du rendu, l’application peut appeler ScriptShapeOpenType pour chaque exécution et doit passer la structure SCRIPT_ANALYSIS correspondante dans la structure SCRIPT_ITEM récupérée par ScriptItemizeOpenType.

Si le texte géré par une application peut inclure du contenu de droite à gauche, l’application utilise les paramètres psControl et psState pour appeler ScriptItemizeOpenType. Toutefois, l’application n’a pas besoin de le faire et peut gérer le texte bidirectionnel lui-même au lieu de s’appuyer sur Uniscribe pour ce faire. Les paramètres psControl et psState sont utiles dans certains scénarios strictement de gauche à droite, par exemple, lorsque le membre fLinkStringBefore de SCRIPT_CONTROL n’est pas spécifique aux scripts de droite à gauche. L’application définit psControl et psState sur NULL pour que ScriptItemizeOpenType interrompe la chaîne Unicode uniquement par du code caractère.

L’application peut définir tous les paramètres sur des valeurs non NULL pour que la fonction effectue une analyse bidirectionnelle Unicode complète. Pour permettre une analyse bidirectionnelle Unicode correcte, la structure SCRIPT_STATE doit être initialisée selon l’ordre de lecture au début du paragraphe, et ScriptItemizeOpenType doit passer l’ensemble du paragraphe. En particulier, le membre uBidiLevel doit être initialisé à 0 pour de gauche à droite et à 1 pour la droite à gauche.

Le membre fRTL de SCRIPT_ANALYSIS est référencé dans SCRIPT_ITEM. Le membre fNumeric de SCRIPT_PROPERTIES est récupéré par ScriptGetProperties. Ces membres fournissent ensemble la même classification que le membre lpClass de GCP_RESULTS, référencé par lpResults dans GetCharacterPlacement.

Les chiffres européens U+0030 à U+0039 peuvent être affichés sous forme de chiffres nationaux, comme indiqué dans le tableau suivant.

SCRIPT_STATE.fDigitSubstitute	SCRIPT_CONTROL.fContextDigits	Formes numériques affichées pour Unicode U+0030 à U+0039
FALSE	Quelconque	Chiffres européens
TRUE	FALSE	Comme spécifié dans le membre uDefaultLanguage de SCRIPT_CONTROL.
TRUE	TRUE	Comme texte fort précédent, par défaut sur uDefaultLanguage membre de SCRIPT_CONTROL.

En mode numérique contextuel, l’une des actions suivantes se produit :

Si le script spécifié par uDefaultLanguage est dans la même direction que la sortie, tous les chiffres rencontrés avant les premières lettres sont rendus dans la langue indiquée par uDefaultLanguage.
Si le script spécifié par uDefaultLanguage est dans le sens opposé de la sortie, tous les chiffres rencontrés avant les premières lettres sont rendus en chiffres européens.

Par exemple, si uDefaultLanguage indique LANG_ARABIC, les chiffres initiaux se trouvent dans Arabic-Indic dans une incorporation de droite à gauche. Toutefois, ils sont en chiffres européens dans une incorporation de gauche à droite.

Pour plus d’informations, consultez Formes numériques.

Les définitions et les caractères de contrôle Unicode, ainsi que leurs effets sur SCRIPT_STATE membres, sont fournis dans le tableau suivant. Pour plus d’informations sur les caractères de contrôle Unicode, consultez La norme Unicode.

Caractères de contrôle Unicode	Signification	Effet sur SCRIPT_STATE
NADS	Remplacez les chiffres européens (NODS) par des formes de chiffres nationaux.	Définissez fDigitSubstitute.
NODS	Utilisez des formes de chiffres nominaux, autrement appelées chiffres européens. Voir NADS.	Effacer fDigitSubstitute.
CUL	Activez l’échange de paires symétriques, par exemple des parenthèses. Pour ces caractères, gauche et droite sont interprétés comme ouvrant et fermant. Il s’agit de la valeur par défaut. Consultez ISS.	Effacer fInhibitSymSwap.
ISS	Empêcher l’échange de paires symétriques. Consultez ASS.	Définissez fInhibitSymSwap.
AAFS	Activez la mise en forme de formulaire arabe pour les formulaires de présentation arabe. Voir IAFS.	Définissez fCharShape.
IAFS	Inhiber la mise en forme de la forme arabe, c’est-à-dire les ligatures et les connexions cursives, pour les formes de présentation arabe. Les caractères arabes nominaux ne sont pas affectés. Il s’agit de la valeur par défaut. Consultez AAFS.	Effacez fCharShape.

Le membre fArabicNumContext de SCRIPT_STATE prend en charge l’affichage contextuel des chiffres dans le texte de script arabe. Il indique si les chiffres sont rendus à l’aide de formes de chiffres de script arabe natif ou de chiffres européens. Au début d’un paragraphe, ce membre doit normalement être initialisé à TRUE pour les paramètres régionaux arabes, ou à FALSE pour tous les autres paramètres régionaux. La fonction met à jour l’état du script à mesure qu’il traite du texte fort.

Le paramètre de sortie pScriptTags indique un tableau avec des entrées parallèles aux éléments. Pour chaque élément, cette fonction récupère une balise de script qui doit être utilisée pour la mise en forme dans toutes les opérations suivantes.

Une balise de script est généralement déterminée par ScriptItemizeOpenType à partir des caractères d’entrée. Si la fonction récupère une balise de script spécifique, l’application doit la passer à d’autres fonctions sans modification. Toutefois, lorsque les caractères sont neutres (par exemple, les chiffres) et que le script ne peut pas être déterminé, l’application doit choisir une balise de script appropriée, par exemple, en fonction de la police et de la langue associées au texte.

Important À compter de Windows 8 : pour conserver la possibilité de s’exécuter sur Windows 7, un module qui utilise Uniscribe doit spécifier Usp10.lib avant gdi32.lib dans sa liste de bibliothèques.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	usp10.h
Bibliothèque	Usp10.lib
DLL	Usp10.dll
Composant redistribuable	Usp10.dll version 1.600 ou ultérieure sur Windows XP