Fonction ScriptStringAnalyse (usp10.h)

Article
08/26/2023

Analyse une chaîne de texte brut.

Syntaxe

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

Paramètres

[in] hdc

Gérez le contexte de l’appareil. Si dwFlags est défini sur SSA_GLYPHS, le handle de contexte de l’appareil est requis. Si dwFlags est défini sur SSA_BREAK, le handle de contexte de l’appareil est facultatif. Si le handle de contexte de l’appareil est fourni, la fonction inspecte la police actuelle dans le contexte de l’appareil. Si la police actuelle est une police symbolique, la fonction traite la chaîne de caractères comme un seul élément neutre SCRIPT_UNDEFINED.

[in] pString

Pointeur vers la chaîne à analyser. La chaîne doit avoir au moins un caractère. Il peut s’agir d’une chaîne Unicode ou utiliser le jeu de caractères d’une page de code Windows ANSI, comme spécifié par le paramètre iCharset .

[in] cString

Longueur de la chaîne à analyser. La longueur est mesurée en caractères pour une chaîne ANSI ou en caractères larges pour une chaîne Unicode. La longueur doit être d’au moins 1.

[in] cGlyphs

Taille de la mémoire tampon de glyphe, en valeurs WORD. Cette taille est requise. La taille recommandée est (1.5 * cString + 16).

[in] iCharset

Descripteur de jeu de caractères. Si la chaîne d’entrée est une chaîne ANSI, ce descripteur est défini sur l’identificateur du jeu de caractères. Si la chaîne est une chaîne Unicode, ce descripteur est défini sur -1.

Les identificateurs de jeu de caractères suivants sont définis :

[in] dwFlags

Indicateurs indiquant l’analyse requise. Ce paramètre peut avoir l’une des valeurs répertoriées dans le tableau suivant.

Valeur	Signification
SSA_BREAK	Récupérer les indicateurs d’arrêt, c’est-à-dire les arrêts de caractères et de mots.
SSA_CLIP	Découpez la chaîne dans iReqWidth.
SSA_DZWG	Fournissez des glyphes de représentation pour les caractères de contrôle.
SSA_FALLBACK	Utilisez des polices de secours.
SSA_FIT	Justifiez la chaîne à iReqWidth.
SSA_GCP	Récupérez les glyphes et pwLogClust manquants avec les conventions GetCharacterPlacement .
SSA_GLYPHS	Générez des glyphes, des positions et des attributs.
SSA_HIDEHOTKEY	Supprimez le premier « & » de la chaîne affichée.
SSA_HOTKEY	Remplacez « & » par le soulignement sur le point de code suivant.
SSA_HOTKEYONLY	Afficher le soulignement uniquement. Le modèle de bits résultant peut être affiché, à l’aide d’un masque XOR, pour activer la visibilité du soulignement de raccourci sans perturber le texte.
SSA_LINK	Appliquez la liaison et l’association de polices d’Asie de l’Est au texte non complexe.
SSA_METAFILE	Écrivez des éléments avec des appels ExtTextOutW , pas avec des glyphes.
SSA_PASSWORD	Chaîne d’entrée en double contenant un caractère unique cString times.
SSA_RTL	Utilisez le niveau d’incorporation de base 1.
SSA_TAB	Développez les onglets.

[in] iReqWidth

Largeur requise pour l’ajustement ou le découpage.

[in, optional] psControl

Pointeur vers une structure SCRIPT_CONTROL . L’application peut définir ce paramètre sur NULL pour indiquer que tous les membres SCRIPT_CONTROL ont la valeur 0.

[in, optional] psState

Pointeur vers une structure SCRIPT_STATE . L’application peut définir ce paramètre sur NULL pour indiquer que tous les membres SCRIPT_STATE ont la valeur 0. Le membre uBidiLevel de SCRIPT_STATE est ignoré. La valeur utilisée est dérivée de l’indicateur SSA_RTL en combinaison avec la disposition du contexte de l’appareil.

[in, optional] piDx

Pointeur vers le tableau dx logique demandé.

[in, optional] pTabdef

Pointeur vers une structure SCRIPT_TABDEF . Cette valeur n’est requise que si dwFlags est défini sur SSA_TAB.

[in] pbInClass

Pointeur vers une valeur BYTE qui indique les classifications de caractères GetCharacterPlacement .

[out] pssa

Pointeur vers une mémoire tampon dans laquelle cette fonction récupère une structure SCRIPT_STRING_ANALYSIS . Cette structure est allouée dynamiquement en cas de retour réussi de la fonction.

Valeur retournée

Retourne S_OK en cas de réussite. La fonction retourne une valeur HRESULT différente de zéro si elle ne réussit pas.

Les retours d’erreur sont les suivants :

E_INVALIDARG. Un paramètre non valide est trouvé.
USP_E_SCRIPT_NOT_IN_FONT. SSA_FALLBACK n’a pas été spécifié ou une police de secours standard est manquante.

La fonction peut également retourner une erreur système convertie en type HRESULT. Un exemple est une erreur retournée en raison d’un manque de mémoire ou d’un appel GDI à l’aide du contexte de l’appareil.

Remarques

L’utilisation de cette fonction est la première étape de la gestion des chaînes de texte brut. Une telle chaîne n’a qu’une seule police, un style, une taille, une couleur, etc. ScriptStringAnalyse alloue des mémoires tampons temporaires pour les analyses d’éléments, les glyphes, les largeurs avancées, etc. Ensuite, il exécute automatiquement ScriptItemize, ScriptShape, ScriptPlace et ScriptBreak. Les résultats sont disponibles via toutes les autres fonctions ScriptString* .

En cas de retour réussi de cette fonction, pssa indique une structure allouée dynamiquement que l’application peut passer successivement aux autres fonctions ScriptString* . L’application doit libérer la structure en appelant ScriptStringFree.

Bien que les fonctionnalités de ScriptStringAnalyse puissent être implémentées par des appels directs à d’autres fonctions, l’utilisation de la fonction elle-même réduit considérablement la quantité de code requise dans l’application pour la gestion de texte brut.

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