Dessin du texte mis en forme

Mise à jour : novembre 2007

Cette rubrique fournit une vue d'ensemble des fonctionnalités de l'objet FormattedText. Cet objet offre un contrôle de bas niveau pour le dessin de texte dans des applications Windows Presentation Foundation (WPF).

Cette rubrique comprend les sections suivantes.

• Vue d'ensemble de la technologie
• Utilisation de l'objet FormattedText
• Migration depuis Win32
• Rubriques connexes

Vue d'ensemble de la technologie

L'objet FormattedText vous permet de dessiner du texte multiligne, dans lequel chaque caractère du texte peut être mis en forme individuellement. L'exemple suivant montre un texte auquel plusieurs formats sont appliqués.

Texte affiché à l'aide de la méthode FormattedText

Remarque :
Pour les développeurs qui migrent depuis l'API Win32, le tableau présenté dans la section Migration depuis Win32 répertorie les indicateurs DrawText de Win32 et leur équivalent approximatif dans Windows Presentation Foundation (WPF).

Raisons pour lesquelles utiliser le texte mis en forme

WPF inclut plusieurs contrôles pour dessiner le texte à l'écran. Chaque contrôle est ciblé sur un scénario différent et dispose de sa propre liste de fonctionnalités et limitations. En général, l'élément TextBlock doit être utilisé lorsqu'une prise en charge de texte limitée est requise, telle qu'une phrase courte dans une interface utilisateur (UI). Label peut être utilisé lorsqu'une prise en charge de texte minimale est nécessaire. Pour plus d'informations, consultez Documents dans Windows Presentation Foundation.

L'objet FormattedText propose des fonctionnalités de mise en forme du texte supérieures aux contrôles de texte de Windows Presentation Foundation (WPF) et peut être utile lorsque vous souhaitez utiliser du texte comme élément décoratif. Pour plus d'informations, consultez la section Conversion du texte mis en forme en géométrie.

En outre, l'objet FormattedText est utile pour créer des objets dérivés de DrawingVisual orientés texte. DrawingVisual est une classe de dessin légère utilisée pour restituer des formes, des images ou du texte. Pour plus d'informations, consultez Test d'atteinte à l'aide de DrawingVisuals, exemple.

Utilisation de l'objet FormattedText

Pour créer le texte mis en forme, appelez le constructeur FormattedText pour créer un objet FormattedText. Une fois que vous avez créé la chaîne initiale de texte mis en forme, vous pouvez appliquer un éventail de mises en forme de styles.

Utilisez la propriété MaxTextWidth pour limiter le texte à une largeur spécifique. Le texte est alors automatiquement renvoyé à la ligne pour éviter de dépasser la largeur spécifiée. Utilisez la propriété MaxTextHeight pour limiter le texte à une hauteur spécifique. Le texte affiche des points de suspension, "...", en lieu et place du texte qui dépasse la hauteur spécifiée.

Texte affiché présentant des retours à la ligne et des points de suspension

Vous pouvez appliquer plusieurs styles de mise en forme à un ou plusieurs caractères. Par exemple, vous pouvez appeler simultanément les méthodes SetFontSize et SetForegroundBrush pour modifier la mise en forme des cinq premiers caractères du texte.

L'exemple de code suivant crée un objet FormattedText et applique ensuite plusieurs styles de mise en forme au texte.

protected override void OnRender(DrawingContext drawingContext)
{
    string testString = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor";

    // Create the initial formatted text string.
    FormattedText formattedText = new FormattedText(
        testString,
        CultureInfo.GetCultureInfo("en-us"),
        FlowDirection.LeftToRight,
        new Typeface("Verdana"),
        32,
        Brushes.Black);

    // Set a maximum width and height. If the text overflows these values, an ellipsis "..." appears.
    formattedText.MaxTextWidth = 300;
    formattedText.MaxTextHeight = 240;

    // Use a larger font size beginning at the first (zero-based) character and continuing for 5 characters.
    // The font size is calculated in terms of points -- not as device-independent pixels.
    formattedText.SetFontSize(36 * (96.0 / 72.0), 0, 5);

    // Use a Bold font weight beginning at the 6th character and continuing for 11 characters.
    formattedText.SetFontWeight(FontWeights.Bold, 6, 11);

    // Use a linear gradient brush beginning at the 6th character and continuing for 11 characters.
    formattedText.SetForegroundBrush(
                            new LinearGradientBrush(
                            Colors.Orange,
                            Colors.Teal,
                            90.0),
                            6, 11);

    // Use an Italic font style beginning at the 28th character and continuing for 28 characters.
    formattedText.SetFontStyle(FontStyles.Italic, 28, 28);

    // Draw the formatted text string to the DrawingContext of the control.
    drawingContext.DrawText(formattedText, new Point(10, 0));
}

Unité de mesure de la taille de police

De même que pour d'autres objets de texte des applications Windows Presentation Foundation (WPF), l'objet FormattedText utilise des pixels indépendants du périphérique comme unité de mesure. La plupart des applications Win32 utilisent toutefois des points comme unité de mesure. Si vous souhaitez afficher le texte en unités de points dans des applications Windows Presentation Foundation (WPF), vous devez convertir unités indépendantes du périphérique (1/96ème de pouce par unité) en points. L'exemple de code suivant vous montre comment effectuer cette conversion.

// The font size is calculated in terms of points -- not as device-independent pixels.
formattedText.SetFontSize(36 * (96.0 / 72.0), 0, 5);

Conversion du texte mis en forme en géométrie

Vous pouvez convertir le texte mis en forme en objets Geometry, ce qui vous permet de créer d'autres types de texte présentant un intérêt visuel. Par exemple, vous pouvez créer un objet Geometry sur la base du contour d'une chaîne de texte.

Contour du texte à l'aide d'un pinceau à dégradé linéaire

Les exemples suivants illustrent plusieurs façons de créer des effets visuels intéressants en modifiant le trait, le remplissage et la surbrillance du texte converti.

Exemple de définition du trait et du remplissage de différentes couleurs

Exemple de pinceau image appliqué au trait

Exemple de pinceau image appliqué au trait et surbrillance

Lorsque le texte est converti en objet Geometry, il ne constitue plus une collection de caractères — autrement dit, vous ne pouvez pas modifier les caractères dans la chaîne de texte. Vous pouvez néanmoins modifier l'apparence du texte converti en changeant ses propriétés de trait et de remplissage. Le trait fait référence au plan du texte converti et le remplissage à la zone située à l'intérieur du plan du texte converti. Pour plus d'informations, consultez Comment : créer du texte avec contour.

Vous pouvez également convertir le texte mis en forme en objet PathGeometry et utiliser celui-ci pour mettre le texte en surbrillance. Par exemple, vous pouvez appliquer une animation à l'objet PathGeometry afin qu'elle suive le plan du texte mis en forme.

L'exemple suivant montre le texte mis en forme qui a été converti en objet PathGeometry. Une ellipse animée suit le tracé des traits du texte rendu.

Sphère suivant la géométrie de tracé du texte

Pour plus d'informations, consultez Comment : créer une animation PathGeometry pour du texte.

Vous pouvez créer d'autres utilisations intéressantes pour le texte mis en forme une fois qu'il a été converti en objet PathGeometry. Par exemple, vous pouvez y insérer une vidéo. Pour plus d'informations, consultez Démonstration d'application d'un texte à une vidéo.

Vidéo s'affichant dans la géométrie de tracé du texte

Migration depuis Win32

Les fonctionnalités de FormattedText utilisées pour dessiner le texte sont similaires à celles de la fonction DrawText de Win32. Pour les développeurs qui migrent depuis l'API Win32, le tableau suivant répertorie les indicateurs DrawText de Win32 et leur équivalent approximatif dans Windows Presentation Foundation (WPF).

Indicateur DrawText	Équivalent WPF	Remarques
DT_BOTTOM	Height	Utilisez la propriété Height pour calculer une position "y" appropriée de DrawText dans Win32.
DT_CALCRECT	Height, Width	Utilisez les propriétés Height et Width pour calculer le rectangle de sortie.
DT_CENTER	TextAlignment	Utilisez la propriété TextAlignment avec la valeur définie à Center.
DT_EDITCONTROL	Aucun	Non requise. La largeur de l'espace et le rendu de la dernière ligne sont les mêmes que dans le contrôle d'édition de l'infrastructure.
DT_END_ELLIPSIS	Trimming	Utilisez la propriété Trimming avec la valeur CharacterEllipsis. Utilisez WordEllipsis pour obtenir DT_END_ELLIPSIS Win32 avec l'ellipse de fin DT_WORD_ELIPSIS. Dans ce cas, des caractères ne sont remplacés par des points de suspension que dans les mots qui ne tiennent pas sur une ligne unique.
DT_EXPAND_TABS	Aucun	Non requise. Des tabulations sont créées automatiquement avec des taquets tous les 4 cadratins, ce qui correspond plus ou moins à la largeur de 8 caractères indépendamment de la langue.
DT_EXTERNALLEADING	Aucun	Non requise. L'espacement externe est toujours inclus dans l'interligne. Utilisez la propriété LineHeight pour créer une interligne définie par l'utilisateur.
DT_HIDEPREFIX	Aucun	Non pris en charge. Supprimez le '&' de la chaîne avant de construire l'objet FormattedText.
DT_LEFT	TextAlignment	Il s'agit de l'alignement de texte par défaut. Utilisez la propriété TextAlignment avec la valeur définie à Left. (WPF uniquement)
DT_MODIFYSTRING	Aucun	Non pris en charge.
DT_NOCLIP	VisualClip	Le découpage n'est pas effectué automatiquement. Si vous souhaitez découper le texte, utilisez la propriété VisualClip.
DT_NOFULLWIDTHCHARBREAK	Aucun	Non pris en charge.
DT_NOPREFIX	Aucun	Non requise. Le caractère '&' présent dans les chaînes est toujours traité comme un caractère normal.
DT_PATHELLIPSIS	Aucun	Utilisez la propriété Trimming avec la valeur WordEllipsis.
DT_PREFIX	Aucun	Non pris en charge. Si vous souhaitez utiliser des traits de soulignement pour du texte, tel qu'une touche d'accès rapide ou une liaison, utilisez la méthode SetTextDecorations.
DT_PREFIXONLY	Aucun	Non pris en charge.
DT_RIGHT	TextAlignment	Utilisez la propriété TextAlignment avec la valeur définie à Right. (WPF uniquement)
DT_RTLREADING	FlowDirection	Affectez à la propriété FlowDirection la valeur RightToLeft.
DT_SINGLELINE	Aucun	Non requis. Les objets FormattedText se comportent comme un contrôle de ligne unique, sauf si la propriété MaxTextWidth est définie ou si le texte contient un retour chariot/saut de ligne.
DT_TABSTOP	Aucun	Les positions des taquets de tabulation définies par l'utilisateur ne sont pas prises en charge.
DT_TOP	Height	Non requise. La justification en haut est la valeur par défaut. D'autres valeurs de positionnement vertical peuvent être définies à l'aide de la propriété Height pour calculer une position "y" appropriée de DrawText dans Win32.
DT_VCENTER	Height	Utilisez la propriété Height pour calculer une position "y" appropriée de DrawText dans Win32.
DT_WORDBREAK	Aucun	Non requise. La césure des mots se fait automatiquement avec les objets FormattedText. Vous ne pouvez pas la désactiver.
DT_WORD_ELLIPSIS	Trimming	Utilisez la propriété Trimming avec la valeur WordEllipsis.

Voir aussi

Tâches

Démonstration d'application d'un texte à une vidéo

Comment : créer du texte avec contour

Concepts

Documents dans Windows Presentation Foundation

Typographie dans Windows Presentation Foundation

Comment : créer une animation PathGeometry pour du texte

Référence

FormattedText