--- title: "Advanced Text Formatting" ms.date: "03/30/2017" dev_langs: - "csharp" - "vb" helpviewer_keywords: - "formatting [WPF]" - "text [WPF]" - "typography [WPF], text formatting" ms.assetid: f0a7986e-f5b2-485c-a27d-f8e922022212 --- # Advanced Text Formatting Windows Presentation Foundation (WPF) provides a robust set of APIs for including text in your application. Layout and user interface (UI) APIs, such as , provide the most common and general-use elements for text presentation. Drawing APIs, such as and , provide a means for including formatted text in drawings. At the most advanced level, WPF provides an extensible text formatting engine to control every aspect of text presentation, such as text store management, text run formatting management, and embedded object management. This topic provides an introduction to WPF text formatting. It focuses on client implementation and use of the WPF text formatting engine. > [!NOTE] > All code examples within this document can be found in the [Advanced Text Formatting Sample](https://github.com/Microsoft/WPF-Samples/tree/master/PerMonitorDPI/TextFormatting). ## Prerequisites This topic assumes that you are familiar with the higher level APIs used for text presentation. Most user scenarios will not require the advanced text formatting APIs discussed in this topic. For an introduction to the different text APIs, see [Documents in WPF](documents-in-wpf.md). ## Advanced Text Formatting The text layout and UI controls in WPF provide formatting properties that allow you to easily include formatted text in your application. These controls expose a number of properties to handle the presentation of text, which includes its typeface, size, and color. Under ordinary circumstances, these controls can handle the majority of text presentation in your application. However, some advanced scenarios require the control of text storage as well as text presentation. WPF provides an extensible text formatting engine for this purpose. The advanced text formatting features found in WPF consist of a text formatting engine, a text store, text runs, and formatting properties. The text formatting engine, , creates lines of text to be used for presentation. This is achieved by initiating the line formatting process and calling the text formatter's . The text formatter retrieves text runs from your text store by calling the store's method. The objects are then formed into objects by the text formatter and given to your application for inspection or display. ## Using the Text Formatter is the WPF text formatting engine and provides services for formatting and breaking text lines. The text formatter can handle different text character formats and paragraph styles, and includes support for international text layout. Unlike a traditional text API, the interacts with a text layout client through a set of callback methods. It requires the client to provide these methods in an implementation of the class. The following diagram illustrates the text layout interaction between the client application and . ![Diagram of text layout client and TextFormatter](./media/advanced-text-formatting/text-layout-textformatter-interaction.png) The text formatter is used to retrieve formatted text lines from the text store, which is an implementation of . This is done by first creating an instance of the text formatter by using the method. This method creates an instance of the text formatter and sets the maximum line height and width values. As soon as an instance of the text formatter is created, the line creation process is started by calling the method. calls back to the text source to retrieve the text and formatting parameters for the runs of text that form a line. In the following example, the process of formatting a text store is shown. The object is used to retrieve text lines from the text store and then format the text line for drawing into the . [!code-csharp[TextFormatterExample#100](~/samples/snippets/csharp/VS_Snippets_Wpf/TextFormatterExample/CSharp/Window1.xaml.cs#100)] [!code-vb[TextFormatterExample#100](~/samples/snippets/visualbasic/VS_Snippets_Wpf/TextFormatterExample/VisualBasic/Window1.xaml.vb#100)] ## Implementing the Client Text Store When you extend the text formatting engine, you are required to implement and manage all aspects of the text store. This is not a trivial task. The text store is responsible for tracking text run properties, paragraph properties, embedded objects, and other similar content. It also provides the text formatter with individual objects which the text formatter uses to create objects. To handle the virtualization of the text store, the text store must be derived from . defines the method the text formatter uses to retrieve text runs from the text store. is the method used by the text formatter to retrieve text runs used in line formatting. The call to is repeatedly made by the text formatter until one of the following conditions occurs: - A or a subclass is returned. - The accumulated width of text runs exceeds the maximum line width specified in either the call to create the text formatter or the call to the text formatter's method. - A Unicode newline sequence, such as "CF", "LF", or "CRLF", is returned. ## Providing Text Runs The core of the text formatting process is the interaction between the text formatter and the text store. Your implementation of provides the text formatter with the objects and the properties with which to format the text runs. This interaction is handled by the method, which is called by the text formatter. The following table shows some of the predefined objects. |TextRun Type|Usage| |------------------|-----------| ||The specialized text run used to pass a representation of character glyphs back to the text formatter.| ||The specialized text run used to provide content in which measuring, hit testing, and drawing is done in whole, such as a button or image within the text.| ||The specialized text run used to mark the end of a line.| ||The specialized text run used to mark the end of a paragraph.| ||The specialized text run used to mark the end of a segment, such as to end the scope affected by a previous run.| ||The specialized text run used to mark a range of hidden characters.| ||The specialized text run used to modify properties of text runs in its scope. The scope extends to the next matching text run, or the next .| Any of the predefined objects can be subclassed. This allows your text source to provide the text formatter with text runs that include custom data. The following example demonstrates a method. This text store returns objects to the text formatter for processing. [!code-csharp[TextFormatterExample#101](~/samples/snippets/csharp/VS_Snippets_Wpf/TextFormatterExample/CSharp/CustomTextSource.cs#101)] [!code-vb[TextFormatterExample#101](~/samples/snippets/visualbasic/VS_Snippets_Wpf/TextFormatterExample/VisualBasic/CustomTextSource.vb#101)] > [!NOTE] > In this example, the text store provides the same text properties to all of the text. Advanced text stores would need to implement their own span management to allow individual characters to have different properties. ## Specifying Formatting Properties objects are formatted by using properties provided by the text store. These properties come in two types, and . handle paragraph inclusive properties such as and . are properties that can be different for each text run within a paragraph, such as foreground brush, , and font size. To implement custom paragraph and custom text run property types, your application must create classes that derive from and respectively. ## See also - [Typography in WPF](typography-in-wpf.md) - [Documents in WPF](documents-in-wpf.md)