GetCharacterPlacementA, fonction (wingdi.h)

Article
03/13/2024

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 insertions, l’ordre dans la chaîne et le rendu des glyphes. 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 était autrefois suffisante pour travailler avec des chaînes de caractères, la nécessité d’utiliser un nombre croissant de langages et de scripts l’a rendue obsolète. Il a été remplacé par la fonctionnalité du module Uniscribe. Pour plus d’informations, consultez Uniscribe.

Il est recommandé qu’une application utilise 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 GetCharacterPlacementA(
  [in]      HDC            hdc,
  [in]      LPCSTR         lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSA lpResults,
  [in]      DWORD          dwFlags
);

Paramètres

[in] hdc

Handle pour 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épassent 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’extension et d’autres uniquement si l’étendue totale n’a pas encore dépassé la valeur maximale. 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 signes diacritiques, mais vous ne souhaiterez peut-être pas les afficher. Utilisez GetFontLanguageInfo pour déterminer si une police prend en charge les signes 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 différentes formes de glyphes en fonction des positions des caractères dans un mot, les caractères non lisibles apparaissent souvent dans la page de codes. Par exemple, dans la page de codes hébreu, il existe des marqueurs de gauche à droite et de droite à gauche, qui permettent de déterminer le positionnement final des caractères dans les chaînes de sortie. Normalement, ceux-ci 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 tout ou partie des 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 codes 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 extensions dans le tableau lpDx afin que la longueur de chaîne soit identique à nMaxExtent. GCP_JUSTIFY ne peut être utilisé qu’avec GCP_MAXEXTENT.
GCP_KASHIDA	Utilisez Kashidas ainsi que, ou à la place, 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 des kashidas sont utilisés, l’application ne peut pas supposer que la définition des tableaux sur la taille de la chaîne d’entrée sera suffisante. (La valeur maximale possible est approximativement dxPageWidth/dxAveCharWidth, où dxPageWidth est la largeur du document et dxAveCharWidth la largeur moyenne des caractères retournée par un appel GetTextMetrics ). Notez que le fait que GetFontLanguageInfo renvoie l’indicateur GCP_KASHIDA ne signifie pas qu’il doit être utilisé dans l’appel à GetCharacterPlacement, mais que l’option est disponible.
GCP_LIGATE	Utilisez des ligatures partout où les caractères sont ligatures. Une ligature se produit lorsqu’un glyphe est utilisé pour deux caractères ou plus. Par exemple, les lettres a et e peuvent être léguées à ?. 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 maximum spécifique est requis pour le nombre de caractères qui seront liggués, 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 fait que GetFontLanguageInfo renvoie 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	Calculez les étendues 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. À utiliser 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 déjà 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 un visuel ordonné pour les langues 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 fait que GetFontLanguageInfo renvoie 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 inférieur et la hauteur est le mot d’ordre supérieur.

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

Remarques

GetCharacterPlacement garantit qu’une application peut traiter correctement le texte, quels que soient 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 l’espacement et les tableaux d’index 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 restitue le texte à l’aide de GetCharacterPlacement pour récupérer les tableaux d’interlignes et 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 intercharacteur pour positionner l’insertion. 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 affecte la valeur NULL au membre correspondant. Pour garantir la récupération des 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 glyphes 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 pendant 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 glyphes et le tableau lpDX . Utilisez ensuite le tableau lpDX pour effectuer le calcul de l’étendue à l’aide de la largeur avancée de chaque caractère, où nMaxFit est le nombre de caractères dont les index de glyphes avancent la largeur est inférieure à la largeur du caractère de début.

Notes

L’en-tête wingdi.h définit GetCharacterPlacement en tant qu’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. La combinaison 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

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