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 davantage d’informations 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 de la structure en octets.

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 doit être réorganisées et si 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 les 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 des index de glyphes doivent être retournés, les index sont pour le tableau lpGlyphes ; si les index de glyphes ne sont pas retournés et que lpOrder est demandé, les index sont pour 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 a la valeur NULL si ces distances ne sont pas nécessaires. Si le rendu des glyphes est effectué, les distances sont pour les glyphes et non pour les caractères, de sorte que le tableau résultant peut être utilisé avec la fonction ExtTextOut .

Les distances dans ce tableau sont dans l’ordre d’affichage. Pour trouver la distance du caractère i 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 a la valeur 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 se trouver immédiatement à gauche du caractère. Par exemple, en hébreu, où le texte s’exécute de droite à gauche, la position d’insertion est à droite du caractère. Si le classement 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 rechercher la valeur de position d’insertion pour le i^iè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 l’une des valeurs suivantes.

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

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 sont utilisées uniquement au premier emplacement du tableau. Tous combinés avec d’autres classifications.

Notez que GCPCLASS_PREBOUNDLTR et GCPCLASS_PREBOUNDRTL s’excluent mutuellement, tout comme GCPCLASSPOSTBOUNDLTR et GCPCLASSPOSTBOUNDRTL.

Pour forcer l’exécution de la disposition d’un caractère d’une manière spécifique, préréglage de la classification pour l’élément de tableau correspondant ; la fonction laisse ces classifications prédéfinies inchangées et calcule les classifications uniquement 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 si le tableau lpClass est fourni.

Si GetFontLanguageInfo ne retourne pas de 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 des glyphes 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 ligatures. En outre, si la réorganisation est nécessaire, 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 ligature, de crénage ou de basculement d’ordre. L’utilisation des valeurs de ce tableau pour les opérations suivantes permet d’économiser à chaque fois le temps nécessaire pour générer les index de glyphe.

Ce tableau contient toujours des index de glyphes 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érés ensemble. (En arabe par exemple, les ligatures à 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 renvoie l’indicateur GCP_GLYPHSHAPE, les glyphes d’un caractère sont différents selon que le caractère se trouve 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 est également le premier caractère d’un mot, et le dernier caractère de la chaîne d’entrée est 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éfilé, cela peut ne pas être vrai. Dans ce cas, il est souhaitable de forcer la mise en forme du premier ou du dernier caractère comme n’étant pas des formes initiales ou finales. Pour ce faire, le premier emplacement du tableau lpGlyphes est utilisé en effectuant une opération OR de la valeur de ligature 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 le maximum requis, 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. Lors de la sortie, cette valeur est définie sur le nombre de glyphes renseignés, dans les tableaux de sortie. Si la substitution de glyphe n’est pas requise (c’est-à-dire que chaque caractère d’entrée est mappé à exactement un glyphe), ce membre est le même que sur 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écifient 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, ce sera le même.

Remarques

Le fait que 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 indicateur GCP_DBCS, GCP_REORDER, GCP_GLYPHSHAPE, GCP_LIGATE, GCP_DIACRITIC ou GCP_KASHIDA n’est retourné, aucun des tableaux n’est requis pour un bon fonctionnement. (Bien qu’elles ne soient pas obligatoires, elles peuvent toujours être utilisées. 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 des 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 glyphes 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 retourne l’indicateur GCP_GLYPHSHAPE, lpOutString donne l’ordre d’affichage lisible de la chaîne passée à GetCharacterPlacement, mais les valeurs seront toujours les caractères nonshapés. Pour un affichage correct, le tableau lpGlyphes doit être utilisé.

Configuration requise

Voir aussi

ExtTextOut

Structures de police et de texte

Vue d’ensemble des polices et du texte

GetCharacterPlacement

GetFontLanguageInfo