Fonction ScriptItemize (usp10.h)

Article
08/26/2023

Décompose une chaîne Unicode en éléments physiques individuellement.

Syntaxe

HRESULT ScriptItemize(
  [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]          int                  *pcItems
);

Paramètres

[in] pwcInChars

Pointeur vers une chaîne Unicode à itemiser.

[in] cInChars

Nombre de caractères dans pwcInChars à examiner.

[in] cMaxItems

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

[in, optional] psControl

Pointeur vers une structure 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 de l’algorithme bidirectionnel initial.

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 pour contenir moins de deux structures SCRIPT_ITEM . La fonction ajoute toujours un élément 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] 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.

La fonction retourne E_INVALIDARG si pwcInChars a la valeur NULL, cInChars a la valeur 0, pItems a la valeur NULL ou cMaxItems< 2.

La fonction retourne E_OUTOFMEMORY si la valeur de cMaxItems est insuffisante. Comme dans tous les cas d’erreur, aucun élément n’est entièrement traité et aucune partie du tableau de sortie ne contient de valeurs définies. Si la fonction retourne E_OUTOFMEMORY, l’application peut l’appeler à nouveau avec une mémoire tampon pItems plus grande.

Remarques

Consultez Affichage de texte avec uniscribe pour une présentation du contexte dans lequel cette fonction est normalement appelée.

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 exécutions qui appartiennent entièrement à un seul élément, à partir de chaque structure SCRIPT_ITEM récupérée par ScriptItemize. Toutefois, il ne doit pas combiner plusieurs éléments en une seule exécution. Plus tard, lors de la mesure ou du rendu, l’application peut appeler ScriptShape pour chaque exécution et doit passer la structure SCRIPT_ANALYSIS récupérée par ScriptItemize dans la structure SCRIPT_ITEM .

Si le texte géré par une application peut inclure n’importe quel contenu de droite à gauche, l’application utilise les paramètres psControl et psState pour appeler ScriptItemize. Toutefois, l’application n’a pas besoin de le faire et peut gérer le texte bidirectionnel elle-même au lieu de s’appuyer sur Uniscribe pour le 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 ScriptItemize 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 en fonction de l’ordre de lecture au début du paragraphe, et ScriptItemize doit être passé tout le paragraphe. En particulier, le membre uBidiLevel doit être initialisé à 0 pour gauche à droite et à 1 pour la droite à gauche.

Le membre fRTL de SCRIPT_ANALYSIS est référencé dans SCRIPT_ITEM enabled="1 ». 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 en tant que 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, la valeur par défaut est 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 la direction opposée à la sortie, tous les chiffres rencontrés avant les premières lettres sont affichés en chiffres européens.

Par exemple, si uDefaultLanguage indique LANG_ARABIC, les chiffres initiaux sont 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 de chiffres.

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, également appelées chiffres européens. Voir NADS.	Effacez 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.	Clear fInhibitSymSwap.
ISS	Empêcher l’échange de paires symétriques. Consultez ASS.	Définissez fInhibitSymSwap.
AAFS	Activer 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.

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 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	usp10.h
Bibliothèque	Usp10.lib
DLL	Usp10.dll
Composant redistribuable	Internet Explorer 5 ou version ultérieure sur Windows Me/98/95