GetTextExtentExPointA, fonction (wingdi.h)
La fonction GetTextExtentExPoint récupère le nombre de caractères d’une chaîne spécifiée qui correspond à un espace spécifié et remplit un tableau avec l’étendue du texte pour chacun de ces caractères. (Une extension de texte est la distance entre le début de l’espace et un caractère qui va tenir dans 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 pour le contexte de l’appareil.
[in] lpszString
Pointeur vers la chaîne terminée par null pour laquelle les extensions doivent être récupérées.
[in] cchString
Nombre de caractères dans la chaîne vers laquelle pointe le paramètre lpszStr . Pour un appel ANSI, il spécifie la longueur de chaîne en octets et pour un unicode, elle spécifie la longueur de chaîne dans les WORD. Notez que pour la fonction ANSI, les caractères dans les pages de codes SBCS prennent un octet chacun, tandis que la plupart des caractères dans les pages de code DBCS prennent deux octets ; pour la fonction Unicode, la plupart des caractères Unicode actuellement définis (ceux du plan multilingue de base (BMP)) sont un MOT tandis que les substituts 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 qui tiennent dans l’espace spécifié par le paramètre nMaxExtent . Lorsque le paramètre lpnFit a la valeur NULL, le paramètre nMaxExtent est ignoré.
[out] lpnDx
Pointeur vers un tableau d’entiers qui reçoit des étendues de chaîne partielle. 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 correspond à l’espace spécifié par le paramètre nMaxExtent . Ce tableau doit avoir au moins autant d’éléments que de caractères spécifiés par le paramètre cchString , car le tableau entier est utilisé en interne. La fonction remplit le tableau avec des extensions valides pour autant de caractères que spécifié par le paramètre lpnFit . Toutes les valeurs du reste du tableau doivent être ignorées. Si alpDx a la valeur NULL, la fonction ne calcule pas les 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 retournée
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 ont la valeur 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 y a des octets dans lpString. Les valeurs INT qui correspondent aux deux octets d’un caractère DBCS correspondent chacune à l’étendue du caractère composite entier.
Notez que les valeurs alpDx pour GetTextExtentExPoint ne sont pas les mêmes que les 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, c’est-à-dire 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 à 90 degrés de l’orientation d’impression, les valeurs retournées par cette fonction ne suivent pas cette règle. Lorsque l’orientation des caractères et l’orientation d’impression correspondent pour une chaîne donnée, cette fonction retourne les dimensions de la chaîne dans la structure SIZE sous la forme { cx : 116, cy : 18 }. Lorsque l’orientation des caractères et l’orientation d’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. Lorsque celles-ci sont arrondies à des unités logiques, vous obtenez des résultats différents de ce qui est retourné par getCharWidth, qui retourne la largeur de chaque caractère individuel arrondi à des unités logiques.
Notes
L’en-tête wingdi.h définit GetTextExtentExPoint 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 |
Voir aussi
Fonctions de police et de texte