GetTextExtentExPointA, fonction (wingdi.h)

La fonction GetTextExtentExPoint récupère le nombre de caractères d’une chaîne spécifiée qui s’ajustera dans un espace spécifié et remplit un tableau avec l’étendue du texte pour chacun de ces caractères. (Une étendue de texte correspond à la distance entre le début de l’espace et un caractère qui s’ajustera à l’espace.) Ces informations sont utiles pour les calculs d’habillage de mots.

Syntaxe

BOOL GetTextExtentExPointA(
  [in]  HDC    hdc,
  [in]  LPCSTR lpszString,
  [in]  int    cchString,
  [in]  int    nMaxExtent,
  [out] LPINT  lpnFit,
  [out] LPINT  lpnDx,
  [out] LPSIZE lpSize
);

Paramètres

[in] hdc

Handle vers le contexte de l’appareil.

[in] lpszString

Pointeur vers la chaîne terminée par null pour laquelle les étendues doivent être récupérées.

[in] cchString

Nombre de caractères dans la chaîne pointée par le paramètre lpszStr. Pour un appel ANSI, il spécifie la longueur de chaîne en octets et pour un Unicode, il spécifie la longueur de chaîne dans les WORDs. Notez que pour la fonction ANSI, les caractères des pages de codes SBCS prennent chacun un octet, tandis que la plupart des caractères des pages de codes DBCS prennent deux octets ; pour la fonction Unicode, les caractères Unicode les plus définis (ceux du plan multilingue de base (BMP)) sont un WORD tandis que les substitutions Unicode sont deux WORD.

[in] nMaxExtent

Largeur maximale autorisée, en unités logiques, de la chaîne mise en forme.

[out] lpnFit

Pointeur vers un entier qui reçoit le nombre maximal de caractères correspondant à l’espace spécifié par le paramètre nMaxExtent. Lorsque le paramètre lpnFit est NULL, le paramètre nMaxExtent est ignoré.

[out] lpnDx

Pointeur vers un tableau d’entiers qui reçoit des étendues de chaîne partielles. Chaque élément du tableau donne la distance, en unités logiques, entre le début de la chaîne et l’un des caractères qui s’intègrent dans l’espace spécifié par le paramètre nMaxExtent. Ce tableau doit avoir au moins autant d’éléments que les caractères spécifiés par le paramètre cchString, car l’ensemble du tableau est utilisé en interne. La fonction remplit le tableau avec des étendues valides pour autant de caractères que spécifiés par le paramètre lpnFit. Toutes les valeurs du reste du tableau doivent être ignorées. Si alpDx est NULL, la fonction ne calcule pas de largeurs de chaîne partielles.

Pour les scripts complexes, où une séquence de caractères peut être représentée par un nombre quelconque de glyphes, les valeurs du tableau alpDx jusqu’au nombre spécifié par le paramètre lpnFit correspondent à un à un avec des points de code. Là encore, vous devez ignorer le reste des valeurs dans le tableau alpDx.

[out] lpSize

Pointeur vers une structure SIZE qui reçoit les dimensions de la chaîne, en unités logiques. Ce paramètre ne peut pas être NULL.

Valeur de retour

Si la fonction réussit, la valeur de retour est différente de zéro.

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

Remarques

Si les paramètres lpnFit et alpDx sont NULL, l’appel de la fonction GetTextExtentExPoint équivaut à appeler la fonction GetTextExtentPoint.

Pour la version ANSI de GetTextExtentExPoint, le tableau lpDx a le même nombre de valeurs INT qu’il existe des octets dans lpString. Les valeurs INT qui correspondent aux deux octets d’un caractère DBCS sont chacune l’étendue du caractère composite entier.

Notez que les valeurs GetTextExtentExPoint ne sont pas identiques aux valeurs lpDx pour ExtTextOut. Pour utiliser les valeurs alpDx dans lpDx, vous devez d’abord les traiter.

Lorsque cette fonction retourne l’étendue du texte, elle suppose que le texte est horizontal, autrement dit, que l’échappement est toujours 0. Cela est vrai pour les mesures horizontales et verticales du texte. Même si vous utilisez une police qui spécifie un échappement différent de zéro, cette fonction n’utilise pas l’angle pendant qu’elle calcule l’étendue du texte. L’application doit la convertir explicitement. Toutefois, lorsque le mode graphique est défini sur GM_ADVANCED et que l’orientation des caractères est de 90 degrés à partir de l’orientation d’impression, les valeurs renvoyées par cette fonction ne suivent pas cette règle. Lorsque l’orientation du caractère et l’orientation d’impression correspondent à une chaîne donnée, cette fonction retourne les dimensions de la chaîne dans la structure SIZE en tant que { cx : 116, cy : 18 }. Lorsque l’orientation du caractère et l’orientation de l’impression sont séparées de 90 degrés pour la même chaîne, cette fonction retourne les dimensions de la chaîne dans la structure SIZE comme { cx : 18, cy : 116 }.

Cette fonction retourne l’étendue de chaque caractère successif dans une chaîne. Quand ces unités sont arrondies à des unités logiques, vous obtenez des résultats différents de ce qui est retourné par la GetCharWidth, qui retourne la largeur de chaque caractère individuel arrondi à des unités logiques.

Exigences

Voir aussi

fonctions de police et de texte

Vue d’ensemble des polices et du texte

GetTextExtentPoint

SIZE