TextFormatter Class

Definition

Namespace:

System.Windows.Media.TextFormatting

Assembly:

PresentationCore.dll

Provides services for formatting text and breaking text lines using a custom text layout client.

public ref class TextFormatter abstract : IDisposable

public abstract class TextFormatter : IDisposable

type TextFormatter = class
    interface IDisposable

Public MustInherit Class TextFormatter
Implements IDisposable

Inheritance

Object

TextFormatter

Implements

IDisposable

Examples

The following example shows how to use a TextFormatter object to generate formatted lines of text that can be displayed as drawing objects.

// Create a TextFormatter object.
TextFormatter formatter = TextFormatter.Create();

// Create common paragraph property settings.
CustomTextParagraphProperties customTextParagraphProperties
    = new CustomTextParagraphProperties();

// Format each line of text from the text store and draw it.
while (textStorePosition < customTextSource.Text.Length)
{
    // Create a textline from the text store using the TextFormatter object.
    using (TextLine myTextLine = formatter.FormatLine(
        customTextSource,
        textStorePosition,
        96 * 6,
        customTextParagraphProperties,
        null))
    {
        // Draw the formatted text into the drawing context.
        myTextLine.Draw(drawingContext, linePosition, InvertAxes.None);

        // Update the index position in the text store.
        textStorePosition += myTextLine.Length;

        // Update the line position coordinate for the displayed line.
        linePosition.Y += myTextLine.Height;
    }
}

' Create a TextFormatter object.
Dim formatter As TextFormatter = TextFormatter.Create()

' Create common paragraph property settings.
Dim customTextParagraphProperties As New CustomTextParagraphProperties()

' Format each line of text from the text store and draw it.
Do While textStorePosition < customTextSource.Text.Length
    ' Create a textline from the text store using the TextFormatter object.
    Using myTextLine As TextLine = formatter.FormatLine(customTextSource, textStorePosition, 96 * 6, customTextParagraphProperties, Nothing)
        ' Draw the formatted text into the drawing context.
        myTextLine.Draw(drawingContext, linePosition, InvertAxes.None)

        ' Update the index position in the text store.
        textStorePosition += myTextLine.Length

        ' Update the line position coordinate for the displayed line.
        linePosition.Y += myTextLine.Height
    End Using
Loop

Remarks

TextFormatter is the WPF text engine that provides services for formatting text and breaking text lines. TextFormatter can handle different text character formats and paragraph styles, and includes support for international text layout.

Unlike a traditional text API, the TextFormatter 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 TextSource class. The following diagram illustrates the interaction of the text formatter client and the text layout client.

Interaction between the text layout client and the TextFormatter object

Text Formatting Services

TextFormatter provides support for text features, such as OpenType typography, as well as support for text run, line, and paragraph level features.

The following table is a list of the key TextFormatter supported services for text features.

Feature	Description
Background brush	The Brush that is used for the background color. See the BackgroundBrush property.
Baseline alignment	Determines the baseline distance of the line. See the BaselineAlignment property.
Font linking	Provides font linking through the use of composite fonts.
Foreground brush	The Brush that is used for the foreground color. See the ForegroundBrush property.
OpenType	Advanced OpenType typographic features, such contextual alternates and standard ligatures. See the TextRunTypographyProperties class properties.
Typeface	Determines the typeface, as well as, weight, style, and stretch. See the Typeface property.
Text decoration	Provides support for TextDecoration objects, such as underline or strikethrough. See the TextDecorations property.
Text effects	Provides support for TextEffect objects. See the TextEffects property.

The following table is a list of the key TextFormatter supported services for paragraph-level features.

Feature	Description
Flow direction	Flow direction of the paragraph - left-to-right, or right-to-left. See the FlowDirection property.
Line indentation	Indentation for each line in the paragraph. See the Indent property.
Marker	Marker characteristics of the first line in the paragraph. See the TextMarkerProperties property.
Paragraph indentation	Indentation for the first line in the paragraph. See the ParagraphIndent property.
Tabs	Includes support for tab alignment and tab leader.
Width	Determine minimum and maximum paragraph width. See the FormatMinMaxParagraphWidth methods.
Word wrap	Determine how text wraps when it reaches the flow edge. See the TextWrapping property.

The following table is a list of the key TextFormatter supported services for line-level features.

Feature	Description
Alignment	Text alignment - left, right, centered, or justified. See the TextAlignment property.
Line height	Height of the line. See the Height property.
Line collapsing	Line collapsing support. See the Collapse method.
Black box measurement	Represents the metrics used to lay out a character in a device font. See the CharacterMetrics class.
Caret support	Caret navigation and editing support. See the TextLine character hit properties, such as GetNextCaretCharacterHit and GetPreviousCaretCharacterHit.

The following table is a list of the key TextFormatter supported services for text run-level features.

Feature	Description
Hidden run	Range of characters that are not visible. See the TextHidden object.
Breaking	Line and paragraph breaking.

Constructors

TextFormatter()

Initializes a new instance of the TextFormatter class.

Methods

Create()	Creates a new instance of the TextFormatter class. This is a static method.
Create(TextFormattingMode)	Creates a new instance of the TextFormatter class with the specified formatting mode. This is a static method.
Dispose()	Releases all managed and unmanaged resources used by the TextFormatter object.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
FormatLine(TextSource, Int32, Double, TextParagraphProperties, TextLineBreak)	Creates a TextLine that is used for formatting and displaying document content.
FormatLine(TextSource, Int32, Double, TextParagraphProperties, TextLineBreak, TextRunCache)	Creates a TextLine that is used for formatting and displaying document content.
FormatMinMaxParagraphWidth(TextSource, Int32, TextParagraphProperties)	Returns a value that represents the smallest and largest possible paragraph width that can fully contain the specified text content.
FormatMinMaxParagraphWidth(TextSource, Int32, TextParagraphProperties, TextRunCache)	Returns a value that represents the smallest and largest possible paragraph width that can fully contain the specified text content.
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetType()	Gets the Type of the current instance. (Inherited from Object)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ToString()	Returns a string that represents the current object. (Inherited from Object)

See also

• Advanced Text Formatting Sample