structure GCP_RESULTSA (wingdi.h)

La structure GCP_RESULTS contient des informations sur les caractères d’une chaîne. Cette structure reçoit les résultats de la fonction GetCharacterPlacement . Pour certaines langues, le premier élément des tableaux peut contenir des informations plus dépendantes de la langue.

Syntaxe

typedef struct tagGCP_RESULTSA {
  DWORD  lStructSize;
  LPSTR  lpOutString;
  UINT   *lpOrder;
  int    *lpDx;
  int    *lpCaretPos;
  LPSTR  lpClass;
  LPWSTR lpGlyphs;
  UINT   nGlyphs;
  int    nMaxFit;
} GCP_RESULTSA, *LPGCP_RESULTSA;

Membres

lStructSize

Taille, en octets, de la structure.

lpOutString

Pointeur vers la mémoire tampon qui reçoit la chaîne de sortie ou a la valeur NULL si la chaîne de sortie n’est pas nécessaire. La chaîne de sortie est une version de la chaîne d’origine qui est dans l’ordre qui sera affiché sur un appareil spécifié. En règle générale, la chaîne de sortie est identique à la chaîne d’origine, mais peut être différente si la chaîne a besoin de réorganiser et que l’indicateur de GCP_REORDER est défini ou si la chaîne d’origine dépasse l’étendue maximale et que l’indicateur GCP_MAXEXTENT est défini.

lpOrder

Pointeur vers le tableau qui reçoit des index de classement ou a la valeur NULL si les index de classement ne sont pas nécessaires. Toutefois, sa signification dépend des autres éléments de GCP_RESULTS. Si les index de glyphe doivent être retournés, les index sont destinés au tableau des lpGlyphes ; si les index de glyphes ne sont pas retournés et que lpOrder est demandé, les index sont destinés à lpOutString. Par exemple, dans ce dernier cas, la valeur de lpOrder[i] est la position de lpString[i] dans la chaîne de sortie lpOutString.

Cela est généralement utilisé lorsque GetFontLanguageInfo retourne l’indicateur GCP_REORDER, ce qui indique que la chaîne d’origine doit être réorganisées. Par exemple, en hébreu, dans lequel le texte s’exécute de droite à gauche, le tableau lpOrder donne les emplacements exacts de chaque élément dans la chaîne d’origine.

lpDx

Pointeur vers le tableau qui reçoit les distances entre les cellules de caractères adjacentes ou est NULL si ces distances ne sont pas nécessaires. Si le rendu du glyphe est effectué, les distances concernent les glyphes et non les caractères, de sorte que le tableau résultant peut être utilisé avec la fonction ExtTextOut .

Les distances de ce tableau sont dans l’ordre d’affichage. Pour trouver la distance du iième caractère dans la chaîne d’origine, utilisez le tableau lpOrder comme suit :


width = lpDx[lpOrder[i]];

lpCaretPos

Pointeur vers le tableau qui reçoit les valeurs de position d’insertion ou est NULL si les positions d’insertion ne sont pas nécessaires. Chaque valeur spécifie la position d’insertion immédiatement avant le caractère correspondant. Dans certaines langues, la position de l’insertion de chaque caractère peut ne pas être immédiatement à gauche du caractère. Par exemple, en hébreu, dans lequel le texte s’exécute de droite à gauche, la position d’insertion est à droite du caractère. Si l’ordre des glyphes est effectué, lpCaretPos correspond à la chaîne d’origine, et non à la chaîne de sortie. Cela signifie que certaines valeurs adjacentes peuvent être identiques.

Les valeurs de ce tableau sont dans l’ordre d’entrée. Pour trouver la valeur de position du signe insertion du iième caractère dans la chaîne d’origine, utilisez le tableau comme suit :


position = lpCaretPos[i];

lpClass

Pointeur vers le tableau qui contient et/ou reçoit des classifications de caractères. Les valeurs indiquent comment disposer des caractères dans la chaîne et sont similaires (mais pas identiques) aux valeurs CT_CTYPE2 retournées par la fonction GetStringTypeEx . Chaque élément du tableau peut être défini sur zéro ou sur l’une des valeurs suivantes.

Valeur Signification
GCPCLASS_ARABIC
Caractère arabe.
GCPCLASS_HEBREW
Caractère hébreu.
GCPCLASS_LATIN
Caractère à partir d’un caractère latin ou d’un autre jeu de caractères sur un octet pour une langue de gauche à droite.
GCPCLASS_LATINNUMBER
Chiffre à partir d’un caractère latin ou d’un autre jeu de caractères sur un octet pour une langue de gauche à droite.
GCPCLASS_LOCALNUMBER
Chiffre à partir du jeu de caractères associé à la police actuelle.
 

En outre, les éléments suivants peuvent être utilisés lors de l’approvisionnement de valeurs dans le tableau lpClass avec l’indicateur GCP_CLASSIN.

Valeur Signification
GCPCLASS_LATINNUMERICSEPARATOR
Entrée uniquement. Caractère utilisé pour séparer les chiffres latins, tels qu’une virgule ou un point décimal.
GCPCLASS_LATINNUMERICTERMINATOR
Entrée uniquement. Caractère utilisé pour mettre fin aux chiffres latins, tels qu’un signe plus ou moins.
GCPCLASS_NEUTRAL
Entrée uniquement. Le caractère n’a pas de classification spécifique.
GCPCLASS_NUMERICSEPARATOR
Entrée uniquement. Caractère utilisé pour séparer les chiffres, tels qu’une virgule ou un point décimal.
 

Pour les langues qui utilisent l’indicateur GCP_REORDER, les valeurs suivantes peuvent également être utilisées avec l’indicateur GCP_CLASSIN. Contrairement aux valeurs précédentes, qui peuvent être utilisées n’importe où dans le tableau lpClass , toutes les valeurs suivantes ne sont utilisées que dans le premier emplacement du tableau. Tous se combinent avec d’autres classifications.

Notez que les GCPCLASS_PREBOUNDLTR et les GCPCLASS_PREBOUNDRTL s’excluent mutuellement, comme le sont GCPCLASSPOSTBOUNDLTR et GCPCLASSPOSTBOUNDRTL.

Valeur Signification
GCPCLASS_PREBOUNDLTR
Définissez lpClass[0] sur GCPCLASS_PREBOUNDLTR pour lier la chaîne à l’ordre de lecture de gauche à droite avant la chaîne.
GCPCLASS_PREBOUNDRTL
Définissez lpClass[0] sur GCPCLASS_PREBOUNDRTL pour lier la chaîne à l’ordre de lecture de droite à gauche avant la chaîne.
GCPCLASS_POSTBOUNDLTR
Définissez lpClass[0] sur GCPCLASS_POSTBOUNDLTR pour lier la chaîne à l’ordre de lecture de gauche à droite après la chaîne.
GCPCLASS_POSTBOUNDRTL
Définissez lpClass[0] sur GCPCLASS_POSTBOUNDRTL pour lier la chaîne à l’ordre de lecture de droite à gauche après la chaîne.
 

Pour forcer la disposition d’un caractère à effectuer de manière spécifique, prédéfinis la classification de l’élément de tableau correspondant ; la fonction laisse ces classifications prédéfinies inchangées et calcule uniquement les classifications pour les éléments de tableau qui ont été définis sur zéro. Les classifications prédéfinies sont utilisées uniquement si l’indicateur GCP_CLASSIN est défini et que le tableau lpClass est fourni.

Si GetFontLanguageInfo ne retourne pas GCP_REORDER pour la police actuelle, seule la valeur GCPCLASS_LATIN est significative.

lpGlyphs

Pointeur vers le tableau qui reçoit les valeurs identifiant les glyphes utilisés pour le rendu de la chaîne ou est NULL si le rendu du glyphe n’est pas nécessaire. Le nombre de glyphes dans le tableau peut être inférieur au nombre de caractères dans la chaîne d’origine si la chaîne contient des glyphes ligés. En outre, si la réorganisation est requise, l’ordre des glyphes peut ne pas être séquentiel.

Ce tableau est utile si plusieurs opérations sont effectuées sur une chaîne qui a n’importe quelle forme de ligation, de crénage ou de basculement d’ordre. L’utilisation des valeurs de ce tableau pour les opérations suivantes permet d’économiser le temps nécessaire pour générer les index de glyphe à chaque fois.

Ce tableau contient toujours des index de glyphe et la valeur ETO_GLYPH_INDEX doit toujours être utilisée lorsque ce tableau est utilisé avec la fonction ExtTextOut .

Lorsque GCP_LIGATE est utilisé, vous pouvez limiter le nombre de caractères qui seront ligés ensemble. (En arabe, par exemple, les ligations à trois caractères sont courantes). Pour ce faire, définissez la valeur maximale requise dans lpGcpResults-lpGlyphs>[0]. Si aucune valeur maximale n’est requise, vous devez définir ce champ sur zéro.

Pour les langues telles que l’arabe, où GetFontLanguageInfo retourne l’indicateur GCP_GLYPHSHAPE, les glyphes d’un caractère seront différents selon que le caractère est au début, au milieu ou à la fin d’un mot. En règle générale, le premier caractère de la chaîne d’entrée sera également le premier caractère d’un mot, et le dernier caractère de la chaîne d’entrée sera traité comme le dernier caractère d’un mot. Toutefois, si la chaîne affichée est un sous-ensemble de la chaîne complète, par exemple lors de l’affichage d’une section de texte défilement, cela peut ne pas être vrai. Dans ce cas, il est souhaitable de forcer les premiers ou les derniers caractères à mettre en forme comme étant des formes initiales ou finales. Pour ce faire, là encore, le premier emplacement du tableau lpGlyphes est utilisé en effectuant une opération OR de la valeur de ligation ci-dessus avec les valeurs GCPGLYPH_LINKBEFORE et/ou GCPGLYPH_LINKAFTER. Par exemple, une valeur de GCPGLYPH_LINKBEFORE | 2 signifie que les ligatures à deux caractères sont la valeur maximale requise, et le premier caractère de la chaîne doit être traité comme s’il se trouve au milieu d’un mot.

nGlyphs

Lors de l’entrée, ce membre doit être défini sur la taille des tableaux pointés par les membres du pointeur de tableau. En sortie, il s’agit du nombre de glyphes remplis, dans les tableaux de sortie. Si la substitution de glyphe n’est pas obligatoire (autrement dit, chaque caractère d’entrée est mappé à exactement un glyphe), ce membre est identique à celui de l’entrée.

nMaxFit

Nombre de caractères qui correspondent aux étendues spécifiées par le paramètre nMaxExtent de la fonction GetCharacterPlacement . Si la valeur GCP_MAXEXTENT ou GCP_JUSTIFY est définie, cette valeur peut être inférieure au nombre de caractères dans la chaîne d’origine. Ce membre est défini, que la valeur GCP_MAXEXTENT ou GCP_JUSTIFY soit spécifiée. Contrairement aux nGlyphes, qui spécifie le nombre de glyphes de sortie, nMaxFit fait référence au nombre de caractères de la chaîne d’entrée. Pour les langues SBCS latines, cela sera le même.

Notes

Si les lpGlyphes, lpOutString ou aucun des deux n’est requis dépend des résultats de l’appel GetFontLanguageInfo .

Dans le cas d’une police pour une langue telle que l’anglais, dans laquelle aucun des indicateurs GCP_DBCS, GCP_REORDER, GCP_GLYPHSHAPE, GCP_LIGATE, GCP_DIACRITIC ou GCP_KASHIDA ne sont retournés, aucun des tableaux n’est nécessaire pour une opération appropriée. (Bien qu’ils ne soient pas obligatoires, ils peuvent toujours être utilisés. Si le tableau lpOutString est utilisé, il sera exactement le même que le lpInputString passé à GetCharacterPlacement.) Notez toutefois que si GCP_MAXEXTENT est utilisé, lpOutString contiendra la chaîne tronquée si elle est utilisée, PAS une copie exacte de l’original.

Dans le cas de polices pour des langues telles que l’hébreu, qui ont une réorganisation, mais qui n’ont généralement pas de formes de glyphe supplémentaires, lpOutString doit être utilisé. Cela donne la chaîne dans l’ordre lisible à l’écran. Toutefois, le tableau lpGlyphes n’est généralement pas nécessaire. (L’hébreu peut avoir des glyphes supplémentaires, si la police est une police TrueType/Open.)

Dans le cas de langues telles que le thaï ou l’arabe, dans lesquelles GetFontLanguageInfo renvoie l’indicateur GCP_GLYPHSHAPE, lpOutString donne l’ordre lisible de la chaîne passée à GetCharacterPlacement, mais les valeurs sont toujours les caractères non formés. Pour un affichage approprié, le tableau lpGlyphes doit être utilisé.

Notes

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

   
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
En-tête wingdi.h (include Windows.h)

Voir aussi

ExtTextOut

Structures de police et de texte

Vue d’ensemble des polices et du texte

GetCharacterPlacement

GetFontLanguageInfo