--- title: "Drawing Formatted Text" ms.date: "03/30/2017" dev_langs: - "csharp" - "vb" helpviewer_keywords: - "text [WPF]" - "typography [WPF], drawing formatted text" - "formatted text [WPF]" - "drawing [WPF], formatted text" ms.assetid: b1d851c1-331c-4814-9964-6fe769db6f1f --- # Drawing Formatted Text This topic provides an overview of the features of the object. This object provides low-level control for drawing text in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications. ## Technology Overview The 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. ![Text displayed using FormattedText object](./media/typography-in-wpf/text-formatted-linear-gradient.jpg) > [!NOTE] > For those developers migrating from the Win32 API, the table in the [Win32 Migration](#win32_migration) section lists the Win32 DrawText flags and the approximate equivalent in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. ### Reasons for Using Formatted Text [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] 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 element should be used when limited text support is required, such as a brief sentence in a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. can be used when minimal text support is required. For more information, see [Documents in WPF](documents-in-wpf.md). The object provides greater text formatting features than [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] 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](#converting_formatted_text). In addition, the object is useful for creating text-oriented -derived objects. is a lightweight drawing class that is used to render shapes, images, or text. For more information, see [Hit Test Using DrawingVisuals Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Visual%20Layer/DrawingVisual). ## Using the FormattedText Object To create formatted text, call the constructor to create a object. Once you have created the initial formatted text string, you can apply a range of formatting styles. Use the property to constrain the text to a specific width. The text will automatically wrap to avoid exceeding the specified width. Use the property to constrain the text to a specific height. The text will display an ellipsis, "…" for the text that exceeds the specified height. ![Text displayed with wordwrap and ellipsis.](./media/drawing-formatted-text/formatted-text-wordwrap-ellipsis.png) You can apply multiple formatting styles to one or more characters. For example, you could call both the and methods to change the formatting of the first five characters in the text. The following code example creates a object and then applies several formatting styles to the text. [!code-csharp[FormattedTextSnippets#FormattedTextSnippets1](~/samples/snippets/csharp/VS_Snippets_Wpf/FormattedTextSnippets/CSharp/Window1.xaml.cs#formattedtextsnippets1)] [!code-vb[FormattedTextSnippets#FormattedTextSnippets1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/FormattedTextSnippets/visualbasic/window1.xaml.vb#formattedtextsnippets1)] ### Font Size Unit of Measure As with other text objects in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications, the 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 [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] 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-csharp[FormattedTextSnippets#FormattedTextSnippets2](~/samples/snippets/csharp/VS_Snippets_Wpf/FormattedTextSnippets/CSharp/Window1.xaml.cs#formattedtextsnippets2)] [!code-vb[FormattedTextSnippets#FormattedTextSnippets2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/FormattedTextSnippets/visualbasic/window1.xaml.vb#formattedtextsnippets2)] ### Converting Formatted Text to a Geometry You can convert formatted text into objects, allowing you to create other types of visually interesting text. For example, you could create a object based on the outline of a text string. ![Text outline using a linear gradient brush](./media/typography-in-wpf/text-outline-linear-gradient.jpg) The following examples illustrate several ways of creating interesting visual effects by modifying the stroke, fill, and highlight of converted text. ![Text with different colors for fill and stroke](./media/typography-in-wpf/fill-stroke-text-effect.jpg) ![Text with image brush applied to stroke](./media/typography-in-wpf/image-brush-application.jpg) ![Text with image brush applied to stroke and highlight](./media/typography-in-wpf/image-brush-text-application.jpg) When text is converted to a 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](how-to-create-outlined-text.md). You can also convert formatted text to a object, and use the object for highlighting the text. For example, you could apply an animation to the object so that the animation follows the outline of the formatted text. The following example shows formatted text that has been converted to a object. An animated ellipse follows the path of the strokes of the rendered text. ![Sphere following the path geometry of text](./media/drawing-formatted-text/sphere-following-geometry-path.gif) Sphere following the path geometry of text For more information, see [How to: Create a PathGeometry Animation for Text](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/ms743610(v=vs.100)). You can create other interesting uses for formatted text once it has been converted to a object. For example, you can clip video to display inside it. ![Video displaying in the path geometry of text](./media/drawing-formatted-text/video-displaying-text-path-geometry.png) ## Win32 Migration The features of 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 [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. |DrawText flag|WPF equivalent|Notes| |-------------------|--------------------|-----------| |DT_BOTTOM||Use the property to compute an appropriate Win32 DrawText 'y' position.| |DT_CALCRECT|, |Use the and properties to calculate the output rectangle.| |DT_CENTER||Use the property with the value set to .| |DT_EDITCONTROL|None|Not required. Space width and last line rendering are the same as in the framework edit control.| |DT_END_ELLIPSIS||Use the property with the value .

Use 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 property to create user-defined line spacing.| |DT_HIDEPREFIX|None|Not supported. Remove the '&' from the string before constructing the object.| |DT_LEFT||This is the default text alignment. Use the property with the value set to . (WPF only)| |DT_MODIFYSTRING|None|Not supported.| |DT_NOCLIP||Clipping does not happen automatically. If you want to clip text, use the 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 property with the value .| |DT_PREFIX|None|Not supported. If you want to use underscores for text, such as an accelerator key or link, use the method.| |DT_PREFIXONLY|None|Not supported.| |DT_RIGHT||Use the property with the value set to . (WPF only)| |DT_RTLREADING||Set the property to .| |DT_SINGLELINE|None|Not required. objects behave as a single line control, unless either the 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||Not required. Top justification is the default. Other vertical positioning values can be defined by using the property to compute an appropriate Win32 DrawText 'y' position.| |DT_VCENTER||Use the property to compute an appropriate Win32 DrawText 'y' position.| |DT_WORDBREAK|None|Not required. Word breaking happens automatically with objects. You cannot disable it.| |DT_WORD_ELLIPSIS||Use the property with the value .| ## See also - - [Documents in WPF](documents-in-wpf.md) - [Typography in WPF](typography-in-wpf.md) - [Create Outlined Text](how-to-create-outlined-text.md) - [How to: Create a PathGeometry Animation for Text](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/ms743610(v=vs.100))