GetCharacterPlacementA, fonction (wingdi.h)

La fonction GetCharacterPlacement récupère des informations sur une chaîne de caractères, telles que les largeurs de caractères, le positionnement insertion, 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 une fois suffisante pour travailler avec des chaînes de caractères, il faut travailler avec un nombre croissant de langages et de scripts qui l’ont rendu obsolète. Elle a été remplacée par les fonctionnalités 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 vers 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 par 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 d’ordre 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 . Comme la fonction traite la chaîne d’entrée, chaque caractère et son étendue sont ajoutés à la sortie, à l’étendue et à d’autres tableaux 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 être 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 est utile uniquement si GetFontLanguageInfo a retourné l’indicateur GCP_REORDER.
GCP_DIACRITIC
Détermine la façon dont les signes diacritiques dans la chaîne sont gérés. Si cette valeur n’est pas définie, les signes 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 nécessitant une réorganisation ou des formes de glyphe différentes 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ébraïque, il existe des marqueurs 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 codes active. Certaines langues, telles que 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 peut uniquement être utilisé conjointement avec GCP_MAXEXTENT.
GCP_KASHIDA
Utilisez Kashidas ainsi que, ou au lieu d’é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é que conjointement avec GCP_JUSTIFY et uniquement si la police (et la langue) prennent en charge Les 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 un nombre de glyphes requis supérieur au nombre de caractères dans la chaîne d’entrée. En raison de cela, lorsque Kashidas sont utilisés, l’application ne peut pas supposer que la définition des tableaux de la taille de la chaîne d’entrée sera suffisante. (La valeur maximale possible sera approximativement dxPageWidth/dxAveCharWidth, où dxPageWidth est la largeur du document et dxAveCharWidth correspond à la largeur moyenne des caractères retournée par un appel GetTextMetrics ).

Notez que tout simplement parce que GetFontLanguageInfo retourne l’indicateur GCP_KASHIDA ne signifie pas qu’il doit être utilisé dans l’appel à GetCharacterPlacement, simplement que l’option est disponible.

GCP_LIGATE
Utilisez des ligations partout où les caractères mentent. Une ligation se produit lorsque un glyphe est utilisé pour deux caractères ou plus. Par exemple, les lettres a et e peuvent mentir à ?. Pour que cela soit utilisé, toutefois, la prise en charge linguistique 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 ligation. Si c’est le cas et qu’une valeur maximale spécifique est requise pour le nombre de caractères qui vont mentir, définissez le nombre dans le premier élément du tableau lpGlyphes . Si la ligation normale est requise, définissez cette valeur sur zéro. Si GCP_LIGATE n’est pas spécifié, aucune ligation 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 signifie que, sauf si la chaîne passée 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 simplement parce que GetFontLanguageInfo retourne l’indicateur GCP_LIGATE ne signifie pas qu’il doit être utilisé dans l’appel à GetCharacterPlacement, simplement que l’option est disponible.

GCP_MAXEXTENT
Les é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 de GCP_REORDER.
GCP_NUMERICOVERRIDE
Certaines langues uniquement. Remplacez la gestion normale des valeurs numériques et traitez-les comme des caractères forts qui correspondent à l’ordre de lecture des chaînes. Utile uniquement avec l’indicateur de GCP_REORDER.
GCP_NUMERICSLATIN
Arabe/Thaï. 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ï. 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 déjà.

Si cet indicateur est défini pour les langues semitiques 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 visuel pour les langues où cela 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 permutables ne sont pas réinitialisés. Par exemple, dans une chaîne de droite à gauche, les valeurs « ( » et « ) » ne sont pas inversées.
GCP_USEKERNING
Utilisez des paires de kerning 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 kerning.

Notez que tout simplement parce que GetFontLanguageInfo retourne l’indicateur GCP_USEKERNING ne signifie pas qu’il doit être utilisé dans l’appel à GetCharacterPlacement, juste que l’option est disponible. La plupart des polices TrueType ont une table de kerning, mais vous n’avez pas à l’utiliser.

 

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.

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 de bas ordre et la hauteur est le mot de haut ordre.

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

Notes

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 l’espacement et les tableaux d’index intercharacter n’est pas toujours nécessaire, sauf si la justification ou le kerning est requis. Pour les polices non latines, les applications peuvent améliorer la vitesse à laquelle la fonction ExtTextOut affiche du texte à l’aide de GetCharacterPlacement pour récupérer l’espacement et les tableaux d’index intercharacter 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 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 GCP_RESULTS.lpGlyphes sont spécifiques à la police actuelle dans le contexte de l’appareil et doivent uniquement être utilisés pour dessiner du texte dans le contexte de l’appareil pendant que cette police reste sélectionnée.

Lorsque vous calculez 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. Pour ce cas, appelez GetCharacterPlacement pour les index glyphes et le tableau lpDX . Utilisez ensuite le tableau lpDX pour effectuer le calcul d’étendue à l’aide de la largeur avancée de chaque caractère, où nMaxFit est le nombre de caractères dont les index glyphes avancent la largeur est inférieure à la largeur du caractère principal.

Notes

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

Voir aussi

ExtTextOut

Fonctions de police et de texte

Vue d’ensemble des polices et du texte

GCP_RESULTS

GetCharABCWidths

GetCharWidth32

GetFontLanguageInfo

GetStringTypeEx

GetTextExtentPoint32

GetTextMetrics