Fonction ScriptItemize (usp10.h)
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.
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.
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 |