Formato de texto avanzadoAdvanced Text Formatting

Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) proporciona un sólido conjunto de API para incluir texto en la aplicación.Windows Presentation Foundation (WPF) provides a robust set of APIs for including text in your application. El interfaz de usuario (UI)user interface (UI) diseño y las TextBlockAPI, como , proporcionan los elementos más comunes y de uso general para la presentación de texto.Layout and interfaz de usuario (UI)user interface (UI) APIs, such as TextBlock, provide the most common and general-use elements for text presentation. Las API de GlyphRunDrawing dibujo, como y FormattedText, proporcionan un medio para incluir texto con formato en dibujos.Drawing APIs, such as GlyphRunDrawing and FormattedText, provide a means for including formatted text in drawings. En el nivel más avanzado, WPFWPF proporciona un motor de formato de texto extensible para controlar todos los aspectos de la presentación de texto, como la administración de almacenes de texto, la administración de formato de ejecución de texto y la administración de objetos incrustados.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.

En este tema se proporciona una introducción al formato de texto WPFWPF.This topic provides an introduction to WPF text formatting. Se centra en la implementación del cliente y el uso del motor de formato de texto WPFWPF.It focuses on client implementation and use of the WPF text formatting engine.

Nota

Todos los ejemplos de código de este documento se pueden encontrar en el ejemplo de formato de texto avanzado.All code examples within this document can be found in the Advanced Text Formatting Sample.

Requisitos previosPrerequisites

En este tema se supone que está familiarizado con las API de nivel superior utilizadas para la presentación de texto.This topic assumes that you are familiar with the higher level APIs used for text presentation. La mayoría de los escenarios de usuario no requerirán las API de formato de texto avanzadas que se describen en este tema.Most user scenarios will not require the advanced text formatting APIs discussed in this topic. Para obtener una introducción a las diferentes API de texto, vea Documentos en WPF .For an introduction to the different text APIs, see Documents in WPF.

Formato de texto avanzadoAdvanced Text Formatting

El diseño IUUI de texto y los controles de WPFWPF proporcionan propiedades de formato que permiten incluir fácilmente texto con formato en la aplicación.The text layout and IUUI controls in WPF provide formatting properties that allow you to easily include formatted text in your application. Estos controles exponen varias propiedades para controlar la presentación de texto, como las de tipo de letra, tamaño y color.These controls expose a number of properties to handle the presentation of text, which includes its typeface, size, and color. En circunstancias normales, estos controles pueden controlar la mayoría de las características de presentación de texto en la aplicación.Under ordinary circumstances, these controls can handle the majority of text presentation in your application. Sin embargo, algunos escenarios avanzados requieren el control del almacenamiento de texto, así como su presentación.However, some advanced scenarios require the control of text storage as well as text presentation. WPFWPF proporciona un motor de formato de texto extensible para este propósito.WPF provides an extensible text formatting engine for this purpose.

Las características avanzadas de formato de texto que se encuentran en WPFWPF constan de un motor de formato de texto, un almacén de texto, ejecuciones de texto y propiedades de formato.The advanced text formatting features found in WPF consist of a text formatting engine, a text store, text runs, and formatting properties. El motor de TextFormatterformato de texto, , crea líneas de texto que se utilizarán para la presentación.The text formatting engine, TextFormatter, creates lines of text to be used for presentation. Esto se logra iniciando el proceso de formato de FormatLinelínea y llamando al formateador de texto .This is achieved by initiating the line formatting process and calling the text formatter's FormatLine. El formateador de texto recupera las ejecuciones de GetTextRun texto del almacén de texto llamando al método de la tienda.The text formatter retrieves text runs from your text store by calling the store's GetTextRun method. A TextRun continuación, el TextLine formateador de texto forma los objetos se forman en objetos y se asignan a la aplicación para su inspección o visualización.The TextRun objects are then formed into TextLine objects by the text formatter and given to your application for inspection or display.

Uso del formateador de textoUsing the Text Formatter

TextFormatteres el motor de formato de texto WPFWPF y proporciona servicios para dar formato y romper líneas de texto.TextFormatter is the WPF text formatting engine and provides services for formatting and breaking text lines. El formateador de texto puede controlar los distintos formatos de caracteres de texto y estilos de párrafo, e incluye compatibilidad para el diseño de texto internacional.The text formatter can handle different text character formats and paragraph styles, and includes support for international text layout.

A diferencia de una TextFormatter API de texto tradicional, interactúa con un cliente de diseño de texto a través de un conjunto de métodos de devolución de llamada.Unlike a traditional text API, the TextFormatter interacts with a text layout client through a set of callback methods. Requiere que el cliente proporcione estos métodos TextSource en una implementación de la clase.It requires the client to provide these methods in an implementation of the TextSource class. En el diagrama siguiente se muestra la TextFormatterinteracción de diseño de texto entre la aplicación cliente y .The following diagram illustrates the text layout interaction between the client application and TextFormatter.

Diagrama de TextFormatter y cliente de diseño de texto

El formateador de texto se utiliza para recuperar líneas de TextSourcetexto con formato del almacén de texto, que es una implementación de .The text formatter is used to retrieve formatted text lines from the text store, which is an implementation of TextSource. Esto se hace creando primero una instancia del Create formateador de texto mediante el método.This is done by first creating an instance of the text formatter by using the Create method. Este método crea una instancia del formateador de texto y establece los valores máximos de alto y ancho de línea.This method creates an instance of the text formatter and sets the maximum line height and width values. Tan pronto como se crea una instancia del formateador de FormatLine texto, el proceso de creación de líneas se inicia llamando al método.As soon as an instance of the text formatter is created, the line creation process is started by calling the FormatLine method. TextFormattervuelve a llamar al origen de texto para recuperar el texto y los parámetros de formato para las ejecuciones de texto que forman una línea.TextFormatter calls back to the text source to retrieve the text and formatting parameters for the runs of text that form a line.

En el ejemplo siguiente, se muestra el proceso para formatear un almacén de texto.In the following example, the process of formatting a text store is shown. El TextFormatter objeto se utiliza para recuperar líneas de texto del almacén DrawingContextde texto y, a continuación, dar formato a la línea de texto para dibujar en el archivo .The TextFormatter object is used to retrieve text lines from the text store and then format the text line for drawing into the DrawingContext.

// Create a DrawingGroup object for storing formatted text.
textDest = new DrawingGroup();
DrawingContext dc = textDest.Open();

// Update the text store.
_textStore.Text = textToFormat.Text;
_textStore.FontRendering = _currentRendering;

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

// Format each line of text from the text store and draw it.
while (textStorePosition < _textStore.Text.Length)
{
   // Create a textline from the text store using the TextFormatter object.
   using (TextLine myTextLine = formatter.FormatLine(
       _textStore,
       textStorePosition,
       96*6,
       new GenericTextParagraphProperties(_currentRendering),
       null))
   {
       // Draw the formatted text into the drawing context.
       myTextLine.Draw(dc, 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;
   }
}

// Persist the drawn text content.
dc.Close();

// Display the formatted text in the DrawingGroup object.
myDrawingBrush.Drawing = textDest;
' Create a DrawingGroup object for storing formatted text.
textDest = New DrawingGroup()
Dim dc As DrawingContext = textDest.Open()

' Update the text store.
_textStore.Text = textToFormat.Text
_textStore.FontRendering = _currentRendering

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

' Format each line of text from the text store and draw it.
Do While textStorePosition < _textStore.Text.Length
   ' Create a textline from the text store using the TextFormatter object.
   Using myTextLine As TextLine = formatter.FormatLine(_textStore, textStorePosition, 96*6, New GenericTextParagraphProperties(_currentRendering), Nothing)
       ' Draw the formatted text into the drawing context.
       myTextLine.Draw(dc, 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

' Persist the drawn text content.
dc.Close()

' Display the formatted text in the DrawingGroup object.
myDrawingBrush.Drawing = textDest

Implementación del almacén de texto de clienteImplementing the Client Text Store

Al ampliar el motor de formato de texto, es necesario que implemente y administre todos los aspectos del almacén de texto.When you extend the text formatting engine, you are required to implement and manage all aspects of the text store. Esta no es una tarea trivial.This is not a trivial task. El almacén de texto es responsable del seguimiento de las propiedades de las ejecuciones de texto, las propiedades de párrafo, los objetos incrustados y otro contenido similar.The text store is responsible for tracking text run properties, paragraph properties, embedded objects, and other similar content. También proporciona el formateador TextRun de texto con objetos TextLine individuales que el formateador de texto utiliza para crear objetos.It also provides the text formatter with individual TextRun objects which the text formatter uses to create TextLine objects.

Para controlar la virtualización del almacén de texto, TextSourceel almacén de texto debe derivarse de .To handle the virtualization of the text store, the text store must be derived from TextSource. TextSourcedefine el método que utiliza el formateador de texto para recuperar ejecuciones de texto del almacén de texto.TextSource defines the method the text formatter uses to retrieve text runs from the text store. GetTextRunes el método utilizado por el formateador de texto para recuperar las ejecuciones de texto utilizadas en el formato de línea.GetTextRun is the method used by the text formatter to retrieve text runs used in line formatting. La llamada GetTextRun a se realiza repetidamente por el formateador de texto hasta que se produce una de las siguientes condiciones:The call to GetTextRun is repeatedly made by the text formatter until one of the following conditions occurs:

  • Se TextEndOfLine devuelve una o una subclase.A TextEndOfLine or a subclass is returned.

  • El ancho acumulado de las ejecuciones de texto supera el ancho de línea máximo especificado en la FormatLine llamada para crear el formateador de texto o la llamada al método del formateador de texto.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 FormatLine method.

  • Se devuelve una secuencia de nueva línea Unicode, como "CF", "LF" o "CRLF".A Unicode newline sequence, such as "CF", "LF", or "CRLF", is returned.

Abastecimiento de ejecuciones de textoProviding Text Runs

La esencia del proceso de formato de texto es la interacción entre el formateador de texto y el almacén de texto.The core of the text formatting process is the interaction between the text formatter and the text store. La implementación de proporciona el formateador de TextSource texto con los TextRun objetos y las propiedades con las que se va a dar formato al texto.Your implementation of TextSource provides the text formatter with the TextRun objects and the properties with which to format the text runs. Esta interacción se GetTextRun controla mediante el método, al que llama el formateador de texto.This interaction is handled by the GetTextRun method, which is called by the text formatter.

En la tabla siguiente se TextRun muestran algunos de los objetos predefinidos.The following table shows some of the predefined TextRun objects.

Tipo TextRunTextRun Type UsoUsage
TextCharacters Ejecución de texto especializada que se usa para devolver una representación de glifos de caracteres al formateador de texto.The specialized text run used to pass a representation of character glyphs back to the text formatter.
TextEmbeddedObject Ejecución de texto especializada que se usa para proporcionar contenido donde la medida, la prueba de posicionamiento y el dibujo se ejecutan de forma global, como un botón o una imagen dentro del texto.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.
TextEndOfLine Ejecución de texto especializada que se usa para marcar el final de una línea.The specialized text run used to mark the end of a line.
TextEndOfParagraph Ejecución de texto especializada que se usa para marcar el final de un párrafo.The specialized text run used to mark the end of a paragraph.
TextEndOfSegment La ejecución de texto especializada utilizada para marcar el final de un TextModifier segmento, por ejemplo, para finalizar el ámbito afectado por una ejecución anterior.The specialized text run used to mark the end of a segment, such as to end the scope affected by a previous TextModifier run.
TextHidden Ejecución de texto especializada que se usa para marcar un intervalo de caracteres ocultos.The specialized text run used to mark a range of hidden characters.
TextModifier Ejecución de texto especializada que se usa para modificar las propiedades de las ejecuciones de texto en su ámbito.The specialized text run used to modify properties of text runs in its scope. El ámbito se extiende TextEndOfSegment a la siguiente TextEndOfParagraphejecución de texto coincidente o a la siguiente.The scope extends to the next matching TextEndOfSegment text run, or the next TextEndOfParagraph.

Cualquiera de los TextRun objetos predefinidos se puede subclase.Any of the predefined TextRun objects can be subclassed. Esto permite que el origen del texto proporcione al formateador de texto ejecuciones de texto que incluyan datos personalizados.This allows your text source to provide the text formatter with text runs that include custom data.

En el ejemplo GetTextRun siguiente se muestra un método.The following example demonstrates a GetTextRun method. Este almacén TextRun de texto devuelve objetos al formateador de texto para su procesamiento.This text store returns TextRun objects to the text formatter for processing.

// Used by the TextFormatter object to retrieve a run of text from the text source.
public override TextRun GetTextRun(int textSourceCharacterIndex)
{
   // Make sure text source index is in bounds.
   if (textSourceCharacterIndex < 0)
      throw new ArgumentOutOfRangeException("textSourceCharacterIndex", "Value must be greater than 0.");
   if (textSourceCharacterIndex >= _text.Length)
   {
      return new TextEndOfParagraph(1);
   }

   // Create TextCharacters using the current font rendering properties.
   if (textSourceCharacterIndex < _text.Length)
   {
      return new TextCharacters(
         _text,
         textSourceCharacterIndex,
         _text.Length - textSourceCharacterIndex,
         new GenericTextRunProperties(_currentRendering));
   }

   // Return an end-of-paragraph if no more text source.
   return new TextEndOfParagraph(1);
}
' Used by the TextFormatter object to retrieve a run of text from the text source.
Public Overrides Function GetTextRun(ByVal textSourceCharacterIndex As Integer) As TextRun
   ' Make sure text source index is in bounds.
   If textSourceCharacterIndex < 0 Then
      Throw New ArgumentOutOfRangeException("textSourceCharacterIndex", "Value must be greater than 0.")
   End If
   If textSourceCharacterIndex >= _text.Length Then
      Return New TextEndOfParagraph(1)
   End If

   ' Create TextCharacters using the current font rendering properties.
   If textSourceCharacterIndex < _text.Length Then
      Return New TextCharacters(_text, textSourceCharacterIndex, _text.Length - textSourceCharacterIndex, New GenericTextRunProperties(_currentRendering))
   End If

   ' Return an end-of-paragraph if no more text source.
   Return New TextEndOfParagraph(1)
End Function

Nota

En este ejemplo, el almacén de texto proporciona las mismas propiedades de texto para todo el texto.In this example, the text store provides the same text properties to all of the text. Los almacenes de texto avanzados tendrían que implementar su propia administración de intervalos para permitir que caracteres individuales tengan propiedades diferentes.Advanced text stores would need to implement their own span management to allow individual characters to have different properties.

Especificación de las propiedades de formatoSpecifying Formatting Properties

TextRunlos objetos se formatean mediante las propiedades proporcionadas por el almacén de texto.TextRun objects are formatted by using properties provided by the text store. Estas propiedades vienen en TextParagraphProperties TextRunPropertiesdos tipos y .These properties come in two types, TextParagraphProperties and TextRunProperties. TextParagraphPropertiescontrolar las propiedades TextAlignment inclusivas de párrafo, como y FlowDirection.TextParagraphProperties handle paragraph inclusive properties such as TextAlignment and FlowDirection. TextRunPropertiesson propiedades que pueden ser diferentes para cada texto que Typefacese ejecuta dentro de un párrafo, como el pincel en primer plano, y el tamaño de fuente.TextRunProperties are properties that can be different for each text run within a paragraph, such as foreground brush, Typeface, and font size. Para implementar tipos de propiedad de ejecución de texto personalizado TextParagraphProperties TextRunProperties y párrafo personalizado, la aplicación debe crear clases que se deriven de y, respectivamente.To implement custom paragraph and custom text run property types, your application must create classes that derive from TextParagraphProperties and TextRunProperties respectively.

Consulte tambiénSee also