GetCharacterPlacementW, fonction (wingdi.h)

Article
03/08/2023

La fonction GetCharacterPlacement récupère des informations sur une chaîne de caractères, telles que la largeur des caractères, le positionnement des caresses, l’ordre dans la chaîne et le rendu du glyphe. Le type d’informations retournées dépend du paramètre dwFlags et est basé sur la police actuellement sélectionnée dans le contexte d’affichage spécifié. La fonction copie les informations dans la structure GCP_RESULTS spécifiée ou dans un ou plusieurs tableaux spécifiés par la structure.

Bien que cette fonction soit autrefois suffisante pour travailler avec des chaînes de caractères, le besoin d’utiliser un nombre croissant de langages et de scripts l’a rendue obsolète. Il a été remplacé par les fonctionnalités du module Uniscribe. Pour plus d’informations, consultez Uniscribe.

Il est recommandé à une application d’utiliser la fonction GetFontLanguageInfo pour déterminer si les valeurs GCP_DIACRITIC, GCP_DBCS, GCP_USEKERNING, GCP_LIGATE, GCP_REORDER, GCP_GLYPHSHAPE et GCP_KASHIDA sont valides pour la police actuellement sélectionnée. S’il n’est pas valide, GetCharacterPlacement ignore la valeur.

La valeur GCP_NODIACRITICS n’est plus définie et ne doit pas être utilisée.

Syntaxe

DWORD GetCharacterPlacementW(
  [in]      HDC            hdc,
  [in]      LPCWSTR        lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSW lpResults,
  [in]      DWORD          dwFlags
);

Paramètres

[in] hdc

Handle dans le contexte de l’appareil.

[in] lpString

Pointeur vers la chaîne de caractères à traiter. La chaîne n’a pas besoin d’être terminée à zéro, car nCount spécifie la longueur de la chaîne.

[in] nCount

Longueur de la chaîne pointée vers lpString.

[in] nMexExtent

Étendue maximale (en unités logiques) à laquelle la chaîne est traitée. Les caractères qui, s’ils sont traités, dépasseraient cette étendue sont ignorés. Les calculs pour les tableaux de classement ou de glyphes requis s’appliquent uniquement aux caractères inclus. Ce paramètre est utilisé uniquement si la valeur GCP_MAXEXTENT est spécifiée dans le paramètre dwFlags . Lorsque la fonction traite la chaîne d’entrée, chaque caractère et son étendue sont ajoutés aux tableaux de sortie, d’étendue et d’autres uniquement si l’étendue totale n’a pas encore dépassé le maximum. Une fois la limite atteinte, le traitement s’arrête.

[in, out] lpResults

Pointeur vers une structure GCP_RESULTS qui reçoit les résultats de la fonction.

[in] dwFlags

Spécifie comment traiter la chaîne dans les tableaux requis. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.

Valeur	Signification
GCP_CLASSIN	Spécifie que le tableau lpClass contient des classifications prédéfinies pour les caractères. Les classifications peuvent être identiques à celles de la sortie. Si la classification particulière d’un caractère n’est pas connue, l’emplacement correspondant dans le tableau doit être défini sur zéro. Pour plus d’informations sur les classifications, consultez GCP_RESULTS. Cela n’est utile que si GetFontLanguageInfo a retourné l’indicateur GCP_REORDER.
GCP_DIACRITIC	Détermine la façon dont les diacritiques dans la chaîne sont gérés. Si cette valeur n’est pas définie, les diacritiques sont traités comme des caractères de largeur nulle. Par exemple, une chaîne hébraïque peut contenir des diacritiques, mais vous ne souhaitez peut-être pas les afficher. Utilisez GetFontLanguageInfo pour déterminer si une police prend en charge les diacritiques. Si c’est le cas, vous pouvez utiliser ou non l’indicateur GCP_DIACRITIC dans l’appel à GetCharacterPlacement, en fonction des besoins de votre application.
GCP_DISPLAYZWG	Pour les langues qui nécessitent une réorganisation ou des formes de glyphe différentes en fonction de la position des caractères dans un mot, les caractères non lisibles apparaissent souvent dans la page de code. Par exemple, dans la page de code hébreu, il existe des marqueurs de gauche à droite et de droite à gauche, pour aider à déterminer le positionnement final des caractères dans les chaînes de sortie. Normalement, ils ne sont pas affichés et sont supprimés des tableaux lpGlyphes et lpDx . Vous pouvez utiliser l’indicateur GCP_DISPLAYZWG pour afficher ces caractères.
GCP_GLYPHSHAPE	Spécifie que certains ou tous les caractères de la chaîne doivent être affichés à l’aide de formes autres que les formes standard définies dans la police actuellement sélectionnée pour la page de code active. Certaines langues, comme l’arabe, ne peuvent pas prendre en charge la création de glyphes, sauf si cette valeur est spécifiée. En règle générale, si GetFontLanguageInfo retourne cette valeur pour une chaîne, cette valeur doit être utilisée avec GetCharacterPlacement.
GCP_JUSTIFY	Ajuste les étendues dans le tableau lpDx afin que la longueur de chaîne soit identique à nMaxExtent. GCP_JUSTIFY ne peuvent être utilisés qu’avec GCP_MAXEXTENT.
GCP_KASHIDA	Utilisez Kashidas ainsi que, ou au lieu de, des étendues ajustées pour modifier la longueur de la chaîne afin qu’elle soit égale à la valeur spécifiée par nMaxExtent. Dans le tableau lpDx , un Kashida est indiqué par un index de justification négatif. GCP_KASHIDA ne peut être utilisé qu’avec GCP_JUSTIFY et uniquement si la police (et la langue) prennent en charge Kashidas. Utilisez GetFontLanguageInfo pour déterminer si la police actuelle prend en charge Kashidas. L’utilisation de Kashidas pour justifier la chaîne peut entraîner une augmentation du nombre de glyphes requis par rapport au nombre de caractères dans la chaîne d’entrée. Pour cette raison, lorsque kashidas sont utilisés, l’application ne peut pas supposer que la définition des tableaux comme étant la taille de la chaîne d’entrée sera suffisante. (Le maximum possible sera dxPageWidth/dxAveCharWidth, où dxPageWidth correspond à la largeur du document et dxAveCharWidth est la largeur moyenne des caractères renvoyée à partir d’un appel GetTextMetrics ). Notez que le simple fait que GetFontLanguageInfo retourne l’indicateur GCP_KASHIDA ne signifie pas qu’il doit être utilisé dans l’appel à GetCharacterPlacement, mais simplement que l’option est disponible.
GCP_LIGATE	Utilisez des ligatures partout où les caractères ligent. Une ligature se produit lorsqu’un glyphe est utilisé pour deux caractères ou plus. Par exemple, les lettres a et e peuvent être ligate à ?. Toutefois, pour que cela soit utilisé, la prise en charge de la langue et la police doivent prendre en charge les glyphes requis (l’exemple ne sera pas traité par défaut en anglais). Utilisez GetFontLanguageInfo pour déterminer si la police actuelle prend en charge la ligature. Si c’est le cas et qu’un nombre maximal spécifique est requis pour le nombre de caractères qui seront ligate, définissez le nombre dans le premier élément du tableau lpGlyphes . Si une ligature normale est requise, définissez cette valeur sur zéro. Si GCP_LIGATE n’est pas spécifié, aucune ligature n’aura lieu. Pour plus d’informations, consultez GCP_RESULTS. Si la valeur GCP_REORDER est généralement requise pour le jeu de caractères, mais n’est pas spécifiée, la sortie n’a pas de sens, sauf si la chaîne transmise est déjà dans l’ordre visuel (autrement dit, le résultat qui est placé dans lpGcpResults-lpOutString> dans un appel à GetCharacterPlacement est la chaîne d’entrée d’un deuxième appel). Notez que le simple fait que GetFontLanguageInfo retourne l’indicateur GCP_LIGATE ne signifie pas qu’il doit être utilisé dans l’appel à GetCharacterPlacement, mais simplement que l’option est disponible.
GCP_MAXEXTENT	Étendues de calcul de la chaîne uniquement tant que l’étendue résultante, en unités logiques, ne dépasse pas les valeurs spécifiées par le paramètre nMaxExtent .
GCP_NEUTRALOVERRIDE	Certaines langues uniquement. Remplacez la gestion normale des neutres et traitez-les comme des caractères forts qui correspondent à l’ordre de lecture des chaînes. Utile uniquement avec l’indicateur GCP_REORDER.
GCP_NUMERICOVERRIDE	Certaines langues uniquement. Remplacez la gestion normale des chiffres et traitez-les comme des caractères forts qui correspondent à l’ordre de lecture des chaînes. Utile uniquement avec l’indicateur GCP_REORDER.
GCP_NUMERICSLATIN	Arabe/thaï uniquement. Utilisez des glyphes latins standard pour les nombres et remplacez la valeur par défaut du système. Pour déterminer si cette option est disponible dans la langue de la police, utilisez GetStringTypeEx pour voir si la langue prend en charge plusieurs formats numériques.
GCP_NUMERICSLOCAL	Arabe/thaï uniquement. Utilisez des glyphes locaux pour les caractères numériques et remplacez la valeur par défaut du système. Pour déterminer si cette option est disponible dans la langue de la police, utilisez GetStringTypeEx pour voir si la langue prend en charge plusieurs formats numériques.
GCP_REORDER	Réorganisez la chaîne. Utilisez pour les langues qui ne sont pas SBCS et l’ordre de lecture de gauche à droite. Si cette valeur n’est pas spécifiée, la chaîne est supposée être dans l’ordre d’affichage. Si cet indicateur est défini pour les langues sémitiques et que le tableau lpClass est utilisé, les deux premiers éléments du tableau sont utilisés pour spécifier l’ordre de lecture au-delà des limites de la chaîne. GCP_CLASS_PREBOUNDRTL et GCP_CLASS_PREBOUNDLTR peuvent être utilisés pour définir l’ordre. Si aucun ordre prédéfini n’est requis, définissez les valeurs sur zéro. Ces valeurs peuvent être combinées avec d’autres valeurs si l’indicateur GCPCLASSIN est défini. Si la valeur GCP_REORDER n’est pas spécifiée, le paramètre lpString est considéré comme étant ordonné pour les langages où il est utilisé, et les champs lpOutString et lpOrder sont ignorés. Utilisez GetFontLanguageInfo pour déterminer si la police actuelle prend en charge la réorganisation.
GCP_SYMSWAPOFF	Langues sémitiques uniquement. Spécifie que les caractères échangeables ne sont pas réinitialisés. Par exemple, dans une chaîne de droite à gauche, les « ( » et « ) » ne sont pas inversés.
GCP_USEKERNING	Utilisez des paires de crénage dans la police (le cas échéant) lors de la création des tableaux de largeurs. Utilisez GetFontLanguageInfo pour déterminer si la police actuelle prend en charge les paires de crénage. Notez que le simple fait que GetFontLanguageInfo retourne l’indicateur GCP_USEKERNING ne signifie pas qu’il doit être utilisé dans l’appel à GetCharacterPlacement, mais que l’option est disponible. La plupart des polices TrueType ont une table de crénage, mais vous n’avez pas besoin de l’utiliser.

La valeur GCP_NODIACRITICS n’est plus définie et ne doit pas être utilisée.

Valeur retournée

Si la fonction réussit, la valeur de retour est la largeur et la hauteur de la chaîne en unités logiques. La largeur est le mot d’ordre bas et la hauteur est le mot d’ordre élevé.

Si la fonction échoue, la valeur de retour est égale à zéro.

Remarques

GetCharacterPlacement garantit qu’une application peut traiter correctement le texte, quel que soit le paramètre international et le type de polices disponibles. Les applications utilisent cette fonction avant d’utiliser la fonction ExtTextOut et à la place de la fonction GetTextExtentPoint32 (et parfois à la place des fonctions GetCharWidth32 et GetCharABCWidths ).

L’utilisation de GetCharacterPlacement pour récupérer des tableaux d’index et d’espacement intercharacter n’est pas toujours nécessaire, sauf si une justification ou un crénage est nécessaire. Pour les polices non latines, les applications peuvent améliorer la vitesse à laquelle la fonction ExtTextOut affiche le texte à l’aide de GetCharacterPlacement pour récupérer l’espacement intercharacter et les tableaux d’index avant d’appeler ExtTextOut. Cela est particulièrement utile lors du rendu du même texte à plusieurs reprises ou lors de l’utilisation de l’espacement intercharactaire pour positionner le caret. Si le tableau de sortie lpGlyphes est utilisé dans l’appel à ExtTextOut, l’indicateur ETO_GLYPH_INDEX doit être défini.

GetCharacterPlacement vérifie les membres lpOrder, lpDX, lpCaretPos, lpOutString et lpGlyphes de la structure GCP_RESULTS et remplit les tableaux correspondants si ces membres ne sont pas définis sur NULL. Si GetCharacterPlacement ne peut pas remplir un tableau, il définit le membre correspondant sur NULL. Pour garantir la récupération d’informations valides, l’application est chargée de définir le membre sur une adresse valide avant d’appeler la fonction et de vérifier la valeur du membre après l’appel. Si les valeurs GCP_JUSTIFY ou GCP_USEKERNING sont spécifiées, les membres lpDX et/ou lpCaretPos doivent avoir des adresses valides.

Notez que les index de glyphe retournés dans les GCP_RESULTS.lpGlyphes sont spécifiques à la police actuelle dans le contexte de l’appareil et ne doivent être utilisés que pour dessiner du texte dans le contexte de l’appareil tant que cette police reste sélectionnée.

Lors du calcul de la justification, si les caractères de fin de la chaîne sont des espaces, la fonction réduit la longueur de la chaîne et supprime les espaces avant de calculer la justification. Si le tableau se compose uniquement d’espaces, la fonction retourne une erreur.

ExtTextOut attend une entrée lpDX pour chaque octet d’une chaîne DBCS, tandis que GetCharacterPlacement affecte une entrée lpDX pour chaque glyphe. Pour corriger cette incompatibilité lors de l’utilisation de cette combinaison de fonctions, utilisez GetGlyphIndices ou développez le tableau lpDX avec des entrées de largeur nulle pour le deuxième octet correspondant d’une paire d’octets DBCS.

Si la largeur logique est inférieure à la largeur du caractère de début dans la chaîne d’entrée, GCP_RESULTS.nMaxFit retourne une valeur incorrecte. Dans ce cas, appelez GetCharacterPlacement pour les index de glyphe et le tableau lpDX . Ensuite, utilisez le tableau lpDX pour effectuer le calcul de l’étendue à l’aide de la largeur avancée de chaque caractère, où nMaxFit correspond au nombre de caractères dont la largeur d’avance des index de glyphe est inférieure à la largeur du caractère de début.

Notes

L’en-tête wingdi.h définit GetCharacterPlacement comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise


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	wingdi.h (inclure Windows.h)
Bibliothèque	Gdi32.lib
DLL	Gdi32.dll