ExtTextOutW, fonction (wingdi.h)

Article
11/20/2024

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ée. Vous pouvez éventuellement fournir des dimensions à utiliser pour le découpage, l’opaquage ou les deux.

Syntaxe

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

Paramètres

[in] hdc

Handle vers 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 être une ou plusieurs des valeurs suivantes.

Valeur	Signification
ETO_CLIPPED	Le texte est clippé 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 traitement spécifique au langage n’est nécessaire. L’indexation de glyphe s’applique uniquement aux polices TrueType, mais l’indicateur peut être utilisé pour les polices bitmap et vectorielles pour indiquer qu’aucun traitement de langage supplémentaire n’est nécessaire et GDI doit traiter la chaîne directement. Notez que tous les index de glyphe 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 glyphe 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 glyphe ne sont pas enregistrés.
ETO_IGNORELANGUAGE	Réservé à l’utilisation du système. Si une application définit cet indicateur, elle perd la prise en charge des scripts internationaux et, dans certains cas, elle ne peut 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 cela est défini, le tableau pointé par 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 linguistique 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 générée à l’aide de 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 pour la 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 de 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’opaquage 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 par zéro, car cbCount spécifie la longueur de la chaîne.

[in] c

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

Cette valeur peut ne 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, lpDx[i] unités logiques séparent les origines de la cellule de caractère i et de la cellule de caractères i + 1.

Valeur de retour

Si la chaîne est dessinée, la valeur de retour est différente de zéro. Toutefois, si la version ANSI de 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 d’alignement de texte actuels 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, seul un 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 trouvera 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 linguistique du Moyen-Orient de Windows : Le texte est disposé dans l’ordre de lecture de droite à gauche, par opposition à l’ordre de gauche à droite par défaut. Cela s’applique uniquement lorsque la police sélectionnée dans le contexte de l’appareil est hébraïque ou 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 est NULL, la fonction ExtTextOut utilise l’espacement par défaut entre les caractères. Les origines des cellules caractères et le contenu du tableau pointés par 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 des appels ExtTextOut suivants.

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

Notez que les valeurs alpDx de GetTextExtentExPoint ne sont pas identiques aux 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 empêche ce comportement et ne doit pas être passé.

En outre, ExtTextOut effectue un traitement par lots interne d’appels avant de passer en mode noyau, ce qui atténue certaines des préoccupations en matière de performances lors du pesage de l’utilisation de PolyTextOut par rapport à ExtTextOut.

Pourboire

ExtTextOut est fortement recommandé sur 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 de polices pour Menu-Item chaînes de texte » dans Utilisation de menus.

Note

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

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	wingdi.h (include Windows.h)
bibliothèque	Gdi32.lib
DLL	Gdi32.dll