Fonction ExtTextOutA (wingdi.h)
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 |
|---|---|
|
Le texte est coupé dans le rectangle. |
|
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. |
|
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. |
|
Pour afficher des nombres, utilisez des chiffres européens. |
|
Pour afficher des nombres, utilisez des chiffres appropriés aux paramètres régionaux. |
|
La couleur d’arrière-plan actuelle doit être utilisée pour remplir le rectangle. |
|
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. |
|
É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.
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 |