| title | description | ms.date | dev_langs | helpviewer_keywords | ms.assetid | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Drawing Formatted Text |
Learn about drawing and controlling formatted text in Windows Presentation Foundation (WPF) applications. |
03/30/2017 |
|
|
b1d851c1-331c-4814-9964-6fe769db6f1f |
This topic provides an overview of the features of the xref:System.Windows.Media.FormattedText object. This object provides low-level control for drawing text in Windows Presentation Foundation (WPF) applications.
The xref:System.Windows.Media.FormattedText object allows you to draw multi-line text, in which each character in the text can be individually formatted. The following example shows text that has several formats applied to it.
Note
For those developers migrating from the Win32 API, the table in the Win32 Migration section lists the Win32 DrawText flags and the approximate equivalent in Windows Presentation Foundation (WPF).
WPF includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own list of features and limitations. In general, the xref:System.Windows.Controls.TextBlock element should be used when limited text support is required, such as a brief sentence in a user interface (UI). xref:System.Windows.Controls.Label can be used when minimal text support is required. For more information, see Documents in WPF.
The xref:System.Windows.Media.FormattedText object provides greater text formatting features than Windows Presentation Foundation (WPF) text controls, and can be useful in cases where you want to use text as a decorative element. For more information, see the following section Converting Formatted Text to a Geometry.
In addition, the xref:System.Windows.Media.FormattedText object is useful for creating text-oriented xref:System.Windows.Media.DrawingVisual-derived objects. xref:System.Windows.Media.DrawingVisual is a lightweight drawing class that is used to render shapes, images, or text. For more information, see Hit Test Using DrawingVisuals Sample.
To create formatted text, call the xref:System.Windows.Media.FormattedText.%23ctor%2A constructor to create a xref:System.Windows.Media.FormattedText object. Once you have created the initial formatted text string, you can apply a range of formatting styles.
Use the xref:System.Windows.Media.FormattedText.MaxTextWidth%2A property to constrain the text to a specific width. The text will automatically wrap to avoid exceeding the specified width. Use the xref:System.Windows.Media.FormattedText.MaxTextHeight%2A property to constrain the text to a specific height. The text will display an ellipsis, "…" for the text that exceeds the specified height.
You can apply multiple formatting styles to one or more characters. For example, you could call both the xref:System.Windows.Media.FormattedText.SetFontSize%2A and xref:System.Windows.Media.FormattedText.SetForegroundBrush%2A methods to change the formatting of the first five characters in the text.
The following code example creates a xref:System.Windows.Media.FormattedText object and then applies several formatting styles to the text.
[!code-csharpFormattedTextSnippets#FormattedTextSnippets1] [!code-vbFormattedTextSnippets#FormattedTextSnippets1]
As with other text objects in Windows Presentation Foundation (WPF) applications, the xref:System.Windows.Media.FormattedText object uses device-independent pixels as the unit of measure. However, most Win32 applications use points as the unit of measure. If you want to use display text in units of points in Windows Presentation Foundation (WPF) applications, you need to convert device-independent units (1/96th inch per unit) to points. The following code example shows how to perform this conversion.
[!code-csharpFormattedTextSnippets#FormattedTextSnippets2] [!code-vbFormattedTextSnippets#FormattedTextSnippets2]
You can convert formatted text into xref:System.Windows.Media.Geometry objects, allowing you to create other types of visually interesting text. For example, you could create a xref:System.Windows.Media.Geometry object based on the outline of a text string.
The following examples illustrate several ways of creating interesting visual effects by modifying the stroke, fill, and highlight of converted text.
When text is converted to a xref:System.Windows.Media.Geometry object, it is no longer a collection of characters—you cannot modify the characters in the text string. However, you can affect the appearance of the converted text by modifying its stroke and fill properties. The stroke refers to the outline of the converted text; the fill refers to the area inside the outline of the converted text. For more information, see Create Outlined Text.
You can also convert formatted text to a xref:System.Windows.Media.PathGeometry object, and use the object for highlighting the text. For example, you could apply an animation to the xref:System.Windows.Media.PathGeometry object so that the animation follows the outline of the formatted text.
The following example shows formatted text that has been converted to a xref:System.Windows.Media.PathGeometry object. An animated ellipse follows the path of the strokes of the rendered text.
Sphere following the path geometry of text
For more information, see How to: Create a PathGeometry Animation for Text.
You can create other interesting uses for formatted text once it has been converted to a xref:System.Windows.Media.PathGeometry object. For example, you can clip video to display inside it.
The features of xref:System.Windows.Media.FormattedText for drawing text are similar to the features of the Win32 DrawText function. For those developers migrating from the Win32 API, the following table lists the Win32 DrawText flags and the approximate equivalent in Windows Presentation Foundation (WPF).
| DrawText flag | WPF equivalent | Notes |
|---|---|---|
| DT_BOTTOM | xref:System.Windows.Media.FormattedText.Height%2A | Use the xref:System.Windows.Media.FormattedText.Height%2A property to compute an appropriate Win32 DrawText 'y' position. |
| DT_CALCRECT | xref:System.Windows.Media.FormattedText.Height%2A, xref:System.Windows.Media.FormattedText.Width%2A | Use the xref:System.Windows.Media.FormattedText.Height%2A and xref:System.Windows.Media.FormattedText.Width%2A properties to calculate the output rectangle. |
| DT_CENTER | xref:System.Windows.Media.FormattedText.TextAlignment%2A | Use the xref:System.Windows.Media.FormattedText.TextAlignment%2A property with the value set to xref:System.Windows.TextAlignment.Center. |
| DT_EDITCONTROL | None | Not required. Space width and last line rendering are the same as in the framework edit control. |
| DT_END_ELLIPSIS | xref:System.Windows.Media.FormattedText.Trimming%2A | Use the xref:System.Windows.Media.FormattedText.Trimming%2A property with the value xref:System.Windows.TextTrimming.CharacterEllipsis. Use xref:System.Windows.TextTrimming.WordEllipsis to get Win32 DT_END_ELLIPSIS with DT_WORD_ELIPSIS end ellipsis—in this case, character ellipsis only occurs on words that do not fit on a single line. |
| DT_EXPAND_TABS | None | Not required. Tabs are automatically expanded to stops every 4 ems, which is approximately the width of 8 language-independent characters. |
| DT_EXTERNALLEADING | None | Not required. External leading is always included in line spacing. Use the xref:System.Windows.Media.FormattedText.LineHeight%2A property to create user-defined line spacing. |
| DT_HIDEPREFIX | None | Not supported. Remove the '&' from the string before constructing the xref:System.Windows.Media.FormattedText object. |
| DT_LEFT | xref:System.Windows.Media.FormattedText.TextAlignment%2A | This is the default text alignment. Use the xref:System.Windows.Media.FormattedText.TextAlignment%2A property with the value set to xref:System.Windows.TextAlignment.Left. (WPF only) |
| DT_MODIFYSTRING | None | Not supported. |
| DT_NOCLIP | xref:System.Windows.Media.Visual.VisualClip%2A | Clipping does not happen automatically. If you want to clip text, use the xref:System.Windows.Media.Visual.VisualClip%2A property. |
| DT_NOFULLWIDTHCHARBREAK | None | Not supported. |
| DT_NOPREFIX | None | Not required. The '&' character in strings is always treated as a normal character. |
| DT_PATHELLIPSIS | None | Use the xref:System.Windows.Media.FormattedText.Trimming%2A property with the value xref:System.Windows.TextTrimming.WordEllipsis. |
| DT_PREFIX | None | Not supported. If you want to use underscores for text, such as an accelerator key or link, use the xref:System.Windows.Media.FormattedText.SetTextDecorations%2A method. |
| DT_PREFIXONLY | None | Not supported. |
| DT_RIGHT | xref:System.Windows.Media.FormattedText.TextAlignment%2A | Use the xref:System.Windows.Media.FormattedText.TextAlignment%2A property with the value set to xref:System.Windows.TextAlignment.Right. (WPF only) |
| DT_RTLREADING | xref:System.Windows.Media.FormattedText.FlowDirection%2A | Set the xref:System.Windows.Media.FormattedText.FlowDirection%2A property to xref:System.Windows.FlowDirection.RightToLeft. |
| DT_SINGLELINE | None | Not required. xref:System.Windows.Media.FormattedText objects behave as a single line control, unless either the xref:System.Windows.Media.FormattedText.MaxTextWidth%2A property is set or the text contains a carriage return/line feed (CR/LF). |
| DT_TABSTOP | None | No support for user-defined tab stop positions. |
| DT_TOP | xref:System.Windows.Media.FormattedText.Height%2A | Not required. Top justification is the default. Other vertical positioning values can be defined by using the xref:System.Windows.Media.FormattedText.Height%2A property to compute an appropriate Win32 DrawText 'y' position. |
| DT_VCENTER | xref:System.Windows.Media.FormattedText.Height%2A | Use the xref:System.Windows.Media.FormattedText.Height%2A property to compute an appropriate Win32 DrawText 'y' position. |
| DT_WORDBREAK | None | Not required. Word breaking happens automatically with xref:System.Windows.Media.FormattedText objects. You cannot disable it. |
| DT_WORD_ELLIPSIS | xref:System.Windows.Media.FormattedText.Trimming%2A | Use the xref:System.Windows.Media.FormattedText.Trimming%2A property with the value xref:System.Windows.TextTrimming.WordEllipsis. |
- xref:System.Windows.Media.FormattedText
- Documents in WPF
- Typography in WPF
- Create Outlined Text
- How to: Create a PathGeometry Animation for Text