Fonction ExtTextOutA (wingdi.h)

Article
08/27/2023

La fonction ExtTextOut dessine du texte à l’aide de la police, de la couleur d’arrière-plan et de la couleur de texte actuellement sélectionnées. Vous pouvez éventuellement fournir des dimensions à utiliser pour le découpage, l’opaquing ou les deux.

Syntaxe

BOOL ExtTextOutA(
  [in] HDC        hdc,
  [in] int        x,
  [in] int        y,
  [in] UINT       options,
  [in] const RECT *lprect,
  [in] LPCSTR     lpString,
  [in] UINT       c,
  [in] const INT  *lpDx
);

Paramètres

[in] hdc

Handle pour le contexte de l’appareil.

[in] x

Coordonnée x, en coordonnées logiques, du point de référence utilisé pour positionner la chaîne.

[in] y

Coordonnée y, en coordonnées logiques, du point de référence utilisé pour positionner la chaîne.

[in] options

Spécifie comment utiliser le rectangle défini par l’application. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.

Valeur	Signification
ETO_CLIPPED	Le texte est coupé dans le rectangle.
ETO_GLYPH_INDEX	Le tableau lpString fait référence à un tableau retourné par GetCharacterPlacement et doit être analysé directement par GDI, car aucun autre traitement spécifique à la langue n’est nécessaire. L’indexation Glyphe s’applique uniquement aux polices TrueType, mais l’indicateur peut être utilisé pour les polices bitmap et vectorielles afin d’indiquer qu’aucun traitement de langage supplémentaire n’est nécessaire et que GDI doit traiter la chaîne directement. Notez que tous les index de glyphes sont des valeurs 16 bits, même si la chaîne est supposée être un tableau de valeurs 8 bits pour les polices raster. Pour ExtTextOutW, les index de glyphes sont enregistrés dans un métafichier. Toutefois, pour afficher les caractères corrects, le métafichier doit être lu à l’aide de la même police. Pour ExtTextOutA, les index de glyphes ne sont pas enregistrés.
ETO_IGNORELANGUAGE	Réservé pour le système. Si une application définit cet indicateur, elle perd la prise en charge des scripts internationaux et, dans certains cas, elle peut n’afficher aucun texte.
ETO_NUMERICSLATIN	Pour afficher des nombres, utilisez des chiffres européens.
ETO_NUMERICSLOCAL	Pour afficher des nombres, utilisez des chiffres appropriés aux paramètres régionaux.
ETO_OPAQUE	La couleur d’arrière-plan actuelle doit être utilisée pour remplir le rectangle.
ETO_PDY	Lorsque ce paramètre est défini, le tableau vers lequel pointe lpDx contient des paires de valeurs. La première valeur de chaque paire est, comme d’habitude, la distance entre les origines des cellules de caractères adjacentes, mais la deuxième valeur est le déplacement le long de la direction verticale de la police.
ETO_RTLREADING	Édition en langue du Moyen-Orient de Windows : Si cette valeur est spécifiée et qu’une police hébraïque ou arabe est sélectionnée dans le contexte de l’appareil, la chaîne est sortie en utilisant l’ordre de lecture de droite à gauche. Si cette valeur n’est pas spécifiée, la chaîne est sortie dans l’ordre de gauche à droite. Le même effet peut être obtenu en définissant la valeur TA_RTLREADING dans SetTextAlign. Cette valeur est conservée à des fins de compatibilité descendante.

Les valeurs ETO_GLYPH_INDEX et ETO_RTLREADING ne peuvent pas être utilisées ensemble. Étant donné que ETO_GLYPH_INDEX implique que tout le traitement du langage a été effectué, la fonction ignore l’indicateur ETO_RTLREADING si elle est également spécifiée.

[in] lprect

Pointeur vers une structure RECT facultative qui spécifie les dimensions, en coordonnées logiques, d’un rectangle utilisé pour le découpage, l’opaquation ou les deux.

[in] lpString

Pointeur vers une chaîne qui spécifie le texte à dessiner. La chaîne n’a pas besoin d’être terminée à zéro, car cbCount spécifie la longueur de la chaîne.

[in] c

Longueur de la chaîne pointée vers lpString.

Cette valeur ne peut pas dépasser 8192.

[in] lpDx

Pointeur vers un tableau facultatif de valeurs qui indiquent la distance entre les origines des cellules de caractères adjacentes. Par exemple, les unités logiques lpDx[i] séparent les origines de la cellule de caractère i et de la cellule de caractère i + 1.

Valeur retournée

Si la chaîne est dessinée, la valeur de retour est différente de zéro. Toutefois, si la version ANSI d’ExtTextOut est appelée avec ETO_GLYPH_INDEX, la fonction retourne TRUE même si la fonction ne fait rien.

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

Remarques

Les paramètres actuels d’alignement du texte pour le contexte d’appareil spécifié déterminent la façon dont le point de référence est utilisé pour positionner le texte. Les paramètres d’alignement du texte sont récupérés en appelant la fonction GetTextAlign . Les paramètres d’alignement du texte sont modifiés en appelant la fonction SetTextAlign . Vous pouvez utiliser les valeurs suivantes pour l’alignement du texte. Un seul indicateur peut être choisi parmi ceux qui affectent l’alignement horizontal et vertical. En outre, un seul des deux indicateurs qui modifient la position actuelle peut être choisi.

Terme	Description
TA_BASELINE	Le point de référence se trouvera sur la ligne de base du texte.
TA_BOTTOM	Le point de référence se trouve sur le bord inférieur du rectangle englobant.
TA_TOP	Le point de référence se trouve sur le bord supérieur du rectangle englobant.
TA_CENTER	Le point de référence est aligné horizontalement avec le centre du rectangle englobant.
TA_LEFT	Le point de référence se trouvera sur le bord gauche du rectangle englobant.
TA_RIGHT	Le point de référence se trouvera sur le bord droit du rectangle englobant.
TA_NOUPDATECP	La position actuelle n’est pas mise à jour après chaque appel de sortie de texte. Le point de référence est passé à la fonction de sortie de texte.
TA_RTLREADING	Édition en langue du Moyen-Orient de Windows : Le texte est disposé dans l’ordre de lecture de droite à gauche, par opposition à l’ordre par défaut de gauche à droite. Cela s’applique uniquement lorsque la police sélectionnée dans le contexte de l’appareil est en hébreu ou en arabe.
TA_UPDATECP	La position actuelle est mise à jour après chaque appel de sortie de texte. La position actuelle est utilisée comme point de référence.

Si le paramètre lpDx a la valeur NULL, la fonction ExtTextOut utilise l’espacement par défaut entre les caractères. Les origines des cellules de caractères et le contenu du tableau vers lequel pointe le paramètre lpDx sont spécifiés en unités logiques. Une origine de cellule de caractère est définie comme l’angle supérieur gauche de la cellule de caractère.

Par défaut, la position actuelle n’est pas utilisée ou mise à jour par cette fonction. Toutefois, une application peut appeler la fonction SetTextAlign avec le paramètre fMode défini sur TA_UPDATECP pour permettre au système d’utiliser et de mettre à jour la position actuelle chaque fois que l’application appelle ExtTextOut pour un contexte d’appareil spécifié. Lorsque cet indicateur est défini, le système ignore les paramètres X et Y lors des appels ExtTextOut suivants.

Pour la version ANSI d’ExtTextOut, le tableau lpDx a le même nombre de valeurs INT qu’il y a des octets dans lpString. Pour les caractères DBCS, vous pouvez répartir le dx dans les entrées lpDx entre l’octet de début et l’octet de fin, à condition que la somme des deux octets s’additionne au dx souhaité. Pour les caractères DBCS avec la version Unicode d’ExtTextOut, chaque glyphe Unicode obtient une seule entrée pdx .

Notez que les valeurs alpDx de 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.

ExtTextOut utilise Uniscribe si nécessaire, ce qui entraîne une secours de police. L’indicateur ETO_IGNORELANGUAGE inhibe ce comportement et ne doit pas être passé.

En outre, ExtTextOut effectue un traitement par lot interne des appels avant la transition vers le mode noyau, ce qui atténue certains problèmes de performances lors de la pondération de l’utilisation de PolyTextOut par rapport à ExtTextOut.

Conseil

ExtTextOut est fortement recommandé par rapport à PolyTextOut pour le développement moderne en raison de sa capacité à gérer l’affichage de différents langages.

Exemples

Pour obtenir un exemple, consultez « Définition des polices pour Menu-Item chaînes de texte » dans Utilisation des menus.

Notes

L’en-tête wingdi.h définit ExtTextOut comme un 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. Le mélange 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