DrawTextA, fonction (winuser.h)

Article
07/21/2023

La fonction DrawText dessine le texte mis en forme dans le rectangle spécifié. Il met en forme le texte en fonction de la méthode spécifiée (développement des tabulations, justification des caractères, lignes cassantes, etc.).

Pour spécifier des options de mise en forme supplémentaires, utilisez la fonction DrawTextEx .

Syntaxe

int DrawTextA(
  [in]      HDC    hdc,
  [in, out] LPCSTR lpchText,
  [in]      int    cchText,
  [in, out] LPRECT lprc,
  [in]      UINT   format
);

Paramètres

[in] hdc

Handle pour le contexte de l’appareil.

[in, out] lpchText

Pointeur vers la chaîne qui spécifie le texte à dessiner. Si le paramètre cchText a la valeur -1, la chaîne doit être terminée par null.

Si uFormat inclut DT_MODIFYSTRING, la fonction peut ajouter jusqu’à quatre caractères supplémentaires à cette chaîne. La mémoire tampon contenant la chaîne doit être suffisamment grande pour prendre en charge ces caractères supplémentaires.

[in] cchText

Longueur, en caractères, de la chaîne. Si cchText a la valeur -1, le paramètre lpchText est supposé être un pointeur vers une chaîne terminée par null et DrawText calcule automatiquement le nombre de caractères.

[in, out] lprc

Pointeur vers une structure RECT qui contient le rectangle (en coordonnées logiques) dans lequel le texte doit être mis en forme.

[in] format

Méthode de mise en forme du texte. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.

Valeur	Signification
DT_BOTTOM	Justifie le texte en bas du rectangle. Cette valeur est utilisée uniquement avec la valeur DT_SINGLELINE.
DT_CALCRECT	Détermine la largeur et la hauteur du rectangle. S’il existe plusieurs lignes de texte, DrawText utilise la largeur du rectangle pointé par le paramètre lpRect et étend la base du rectangle pour lier la dernière ligne de texte. Si le mot le plus grand est plus large que le rectangle, la largeur est étendue. Si le texte est inférieur à la largeur du rectangle, la largeur est réduite. S’il n’y a qu’une seule ligne de texte, DrawText modifie le côté droit du rectangle afin qu’il limite le dernier caractère de la ligne. Dans les deux cas, DrawText renvoie la hauteur du texte mis en forme, mais ne dessine pas le texte.
DT_CENTER	Centre le texte horizontalement dans le rectangle.
DT_EDITCONTROL	Duplique les caractéristiques d’affichage de texte d’un contrôle d’édition multiligne. Plus précisément, la largeur moyenne des caractères est calculée de la même manière que pour un contrôle d’édition, et la fonction n’affiche pas de dernière ligne partiellement visible.
DT_END_ELLIPSIS	Pour le texte affiché, si la fin d’une chaîne ne tient pas dans le rectangle, elle est tronquée et des points de suspension sont ajoutés. Si un mot qui ne se trouve pas à la fin de la chaîne dépasse les limites du rectangle, il est tronqué sans ellipses. La chaîne n’est pas modifiée, sauf si l’indicateur DT_MODIFYSTRING est spécifié. Comparez avec DT_PATH_ELLIPSIS et DT_WORD_ELLIPSIS.
DT_EXPANDTABS	Développe des caractères de tabulation. Le nombre par défaut de caractères par tabulation est huit. Les valeurs DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS et DT_END_ELLIPSIS ne peuvent pas être utilisées avec la valeur DT_EXPANDTABS.
DT_EXTERNALLEADING	Inclut l'espacement externe de la police dans la hauteur de ligne. Normalement, le début externe n’est pas inclus dans la hauteur d’une ligne de texte.
DT_HIDEPREFIX	Ignore le caractère de préfixe esperluette (&) dans le texte. La lettre qui suit ne sera pas soulignée, mais d’autres caractères de préfixe mnémonique sont toujours traités. Exemple : chaîne d’entrée : « A&bc&&d » normal : « Abc&d » DT_HIDEPREFIX : « Abc&d » Comparez avec DT_NOPREFIX et DT_PREFIXONLY.
DT_INTERNAL	Utilise la police système pour calculer la métrique du texte.
DT_LEFT	Aligne le texte à gauche.
DT_MODIFYSTRING	Modifie la chaîne spécifiée pour qu’elle corresponde au texte affiché. Cette valeur n’a aucun effet, sauf si DT_END_ELLIPSIS ou DT_PATH_ELLIPSIS est spécifié.
DT_NOCLIP	Dessine sans découpage. DrawText est un peu plus rapide lorsque DT_NOCLIP est utilisé.
DT_NOFULLWIDTHCHARBREAK	Empêche un saut de ligne au niveau d’une chaîne de caractères double largeur (DBCS), afin que la règle de saut de ligne soit équivalente aux chaînes SBCS. Par exemple, cela peut être utilisé dans les fenêtres coréennes, pour plus de lisibilité des étiquettes d’icônes. Cette valeur n’a aucun effet, sauf si DT_WORDBREAK est spécifié.
DT_NOPREFIX	Désactive le traitement des caractères de préfixe. Normalement, DrawText interprète le caractère de préfixe mnémonique & comme une directive pour souligner le caractère qui suit, et les caractères de préfixe mnémonique && en tant que directive pour imprimer une seule &. En spécifiant DT_NOPREFIX, ce traitement est désactivé. Par exemple, Exemple : chaîne d’entrée : « A&bc&&d » normal : « Abc&d » DT_NOPREFIX : « A&bc&&d » Comparez avec DT_HIDEPREFIX et DT_PREFIXONLY.
DT_PATH_ELLIPSIS	Pour le texte affiché, remplace les caractères au milieu de la chaîne par des points de suspension afin que le résultat corresponde au rectangle spécifié. Si la chaîne contient des caractères barre oblique inverse (\\), DT_PATH_ELLIPSIS conserve autant que possible du texte après la dernière barre oblique inverse. La chaîne n’est pas modifiée, sauf si l’indicateur DT_MODIFYSTRING est spécifié. Comparez avec DT_END_ELLIPSIS et DT_WORD_ELLIPSIS.
DT_PREFIXONLY	Dessine uniquement un trait de soulignement à la position du caractère suivant le caractère de préfixe d’esperluette (&). Ne dessine aucun autre caractère dans la chaîne. Par exemple, Exemple : chaîne d’entrée : « A&bc&&d »n normal : « Abc&d » DT_PREFIXONLY : " _ » Comparez avec DT_HIDEPREFIX et DT_NOPREFIX.
DT_RIGHT	Aligne le texte à droite.
DT_RTLREADING	Disposition dans l’ordre de lecture de droite à gauche pour le texte bidirectionnel lorsque la police sélectionnée dans le hdc est une police hébraïque ou arabe. L’ordre de lecture par défaut pour tout le texte est de gauche à droite.
DT_SINGLELINE	Affiche le texte sur une seule ligne uniquement. Les retours chariots et les sauts de ligne n’interrompent pas la ligne.
DT_TABSTOP	Définit les taquets de tabulation. Les bits 15-8 (octets d’ordre supérieur du mot de bas ordre) du paramètre uFormat spécifient le nombre de caractères pour chaque onglet. Le nombre de caractères par défaut par onglet est de huit. Les valeurs DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP et DT_NOPREFIX ne peuvent pas être utilisées avec la valeur DT_TABSTOP.
DT_TOP	Justifie le texte en haut du rectangle.
DT_VCENTER	Centre le texte verticalement. Cette valeur est utilisée uniquement avec la valeur DT_SINGLELINE.
DT_WORDBREAK	Casse les mots. Les lignes sont automatiquement rompues entre les mots si un mot dépasse le bord du rectangle spécifié par le paramètre lpRect . Une séquence d’alimentation de ligne de retour chariot interrompt également la ligne. Si ce n’est pas spécifié, la sortie se trouve sur une seule ligne.
DT_WORD_ELLIPSIS	Tronque tout mot qui ne tient pas dans le rectangle et ajoute des points de suspension. Comparez avec DT_END_ELLIPSIS et DT_PATH_ELLIPSIS.

Valeur retournée

Si la fonction réussit, la valeur de retour est la hauteur du texte en unités logiques. Si DT_VCENTER ou DT_BOTTOM est spécifié, la valeur de retour est le décalage entre lpRect->top et le bas du texte dessiné

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

Remarques

La fonction DrawText utilise la police, la couleur de texte et la couleur d’arrière-plan sélectionnées du contexte d’appareil pour dessiner le texte. Sauf si le format DT_NOCLIP est utilisé, DrawText clipse le texte afin qu’il ne s’affiche pas en dehors du rectangle spécifié. Notez que le texte avec un surplomb significatif peut être coupé, par exemple, un « W » initial dans la chaîne de texte ou du texte qui est en italique. Toute mise en forme est supposée avoir plusieurs lignes, sauf si le format DT_SINGLELINE est spécifié.

Si la police sélectionnée est trop grande pour le rectangle spécifié, la fonction DrawText n’essaie pas de remplacer une police plus petite.

Le mode d’alignement du texte pour le contexte de l’appareil doit inclure les indicateurs TA_LEFT, TA_TOP et TA_NOUPDATECP.

Notes

L’en-tête winuser.h définit DrawText 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]
Plateforme cible	Windows
En-tête	winuser.h (inclure Windows.h)
Bibliothèque	User32.lib
DLL	User32.dll
Ensemble d’API	ext-ms-win-ntuser-misc-l1-1-0 (introduit dans Windows 8)