Dibujar texto con formatoDrawing Formatted Text

En este tema se proporciona FormattedText información general sobre las características del objeto.This topic provides an overview of the features of the FormattedText object. Este objeto proporciona control de nivel bajo para dibujar texto en aplicaciones Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF).This object provides low-level control for drawing text in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) applications.

Información general sobre la tecnologíaTechnology Overview

El FormattedText objeto permite dibujar texto de varias líneas, en el que cada carácter del texto se puede formatear individualmente.The FormattedText object allows you to draw multi-line text, in which each character in the text can be individually formatted. En el ejemplo siguiente se muestra texto al que se le aplicaron varios formatos.The following example shows text that has several formats applied to it.

Texto mostrado mediante un objeto FormattedText

Nota

Para los desarrolladores que migran desde la API de Win32, la tabla de la sección Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF)Migración de Win32 enumera los indicadores DrawText de Win32 y el equivalente aproximado en .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)Windows Presentation Foundation (WPF).

Razones para utilizar el texto con formatoReasons for Using Formatted Text

WPFWPF incluye varios controles para dibujar texto en la pantalla.includes multiple controls for drawing text to the screen. Cada control se destina a un escenario diferente y tiene su propia lista de características y limitaciones.Each control is targeted to a different scenario and has its own list of features and limitations. En general, TextBlock el elemento debe utilizarse cuando se requiere compatibilidad interfaz de usuario (UI)user interface (UI)limitada con texto, como una breve frase en un archivo .In general, the TextBlock element should be used when limited text support is required, such as a brief sentence in a interfaz de usuario (UI)user interface (UI). Labelse puede utilizar cuando se requiere un soporte de texto mínimo.Label can be used when minimal text support is required. Para obtener más información, vea Documentos en WPF.For more information, see Documents in WPF.

El FormattedText objeto proporciona mayores Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) características de formato de texto que los controles de texto y puede ser útil en los casos en los que desea utilizar texto como elemento decorativo.The FormattedText object provides greater text formatting features than Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) text controls, and can be useful in cases where you want to use text as a decorative element. Para obtener más información, consulte la sección siguiente Convertir texto con formato en una geometría.For more information, see the following section Converting Formatted Text to a Geometry.

Además, FormattedText el objeto es útil DrawingVisualpara crear objetos derivados orientados al texto.In addition, the FormattedText object is useful for creating text-oriented DrawingVisual-derived objects. DrawingVisuales una clase de dibujo ligera que se utiliza para representar formas, imágenes o texto.DrawingVisual is a lightweight drawing class that is used to render shapes, images, or text. Para obtener más información, consulte Hit Test Using DrawingVisuals Sample.For more information, see Hit Test Using DrawingVisuals Sample.

Utilizar el objeto FormattedTextUsing the FormattedText Object

Para crear texto con FormattedText formato, llame FormattedText al constructor para crear un objeto.To create formatted text, call the FormattedText constructor to create a FormattedText object. Una vez que haya creado la cadena inicial de texto con formato, podrá aplicar una gama de estilos de formato.Once you have created the initial formatted text string, you can apply a range of formatting styles.

Utilice MaxTextWidth la propiedad para restringir el texto a un ancho específico.Use the MaxTextWidth property to constrain the text to a specific width. El texto se ajustará automáticamente para evitar superar el ancho especificado.The text will automatically wrap to avoid exceeding the specified width. Utilice MaxTextHeight la propiedad para restringir el texto a una altura específica.Use the MaxTextHeight property to constrain the text to a specific height. El texto mostrará puntos suspensivos ("...") para el texto que supere el alto especificado.The text will display an ellipsis, "…" for the text that exceeds the specified height.

Texto mostrado con textwrap y puntos suspensivos.

Puede aplicar varios estilos de formato a uno o más caracteres.You can apply multiple formatting styles to one or more characters. Por ejemplo, podría llamar SetFontSize SetForegroundBrush a los métodos y y para cambiar el formato de los primeros cinco caracteres del texto.For example, you could call both the SetFontSize and SetForegroundBrush methods to change the formatting of the first five characters in the text.

En el ejemplo FormattedText de código siguiente se crea un objeto y, a continuación, se aplican varios estilos de formato al texto.The following code example creates a FormattedText object and then applies several formatting styles to the text.

protected override void OnRender(DrawingContext drawingContext)
{
    string testString = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor";

    // Create the initial formatted text string.
    FormattedText formattedText = new FormattedText(
        testString,
        CultureInfo.GetCultureInfo("en-us"),
        FlowDirection.LeftToRight,
        new Typeface("Verdana"),
        32,
        Brushes.Black);

    // Set a maximum width and height. If the text overflows these values, an ellipsis "..." appears.
    formattedText.MaxTextWidth = 300;
    formattedText.MaxTextHeight = 240;

    // Use a larger font size beginning at the first (zero-based) character and continuing for 5 characters.
    // The font size is calculated in terms of points -- not as device-independent pixels.
    formattedText.SetFontSize(36 * (96.0 / 72.0), 0, 5);

    // Use a Bold font weight beginning at the 6th character and continuing for 11 characters.
    formattedText.SetFontWeight(FontWeights.Bold, 6, 11);

    // Use a linear gradient brush beginning at the 6th character and continuing for 11 characters.
    formattedText.SetForegroundBrush(
                            new LinearGradientBrush(
                            Colors.Orange,
                            Colors.Teal,
                            90.0),
                            6, 11);

    // Use an Italic font style beginning at the 28th character and continuing for 28 characters.
    formattedText.SetFontStyle(FontStyles.Italic, 28, 28);

    // Draw the formatted text string to the DrawingContext of the control.
    drawingContext.DrawText(formattedText, new Point(10, 0));
}
Protected Overrides Sub OnRender(ByVal drawingContext As DrawingContext)
    Dim testString As String = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor"

    ' Create the initial formatted text string.
    Dim formattedText As New FormattedText(testString, CultureInfo.GetCultureInfo("en-us"), FlowDirection.LeftToRight, New Typeface("Verdana"), 32, Brushes.Black)

    ' Set a maximum width and height. If the text overflows these values, an ellipsis "..." appears.
    formattedText.MaxTextWidth = 300
    formattedText.MaxTextHeight = 240

    ' Use a larger font size beginning at the first (zero-based) character and continuing for 5 characters.
    ' The font size is calculated in terms of points -- not as device-independent pixels.
    formattedText.SetFontSize(36 * (96.0 / 72.0), 0, 5)

    ' Use a Bold font weight beginning at the 6th character and continuing for 11 characters.
    formattedText.SetFontWeight(FontWeights.Bold, 6, 11)

    ' Use a linear gradient brush beginning at the 6th character and continuing for 11 characters.
    formattedText.SetForegroundBrush(New LinearGradientBrush(Colors.Orange, Colors.Teal, 90.0), 6, 11)

    ' Use an Italic font style beginning at the 28th character and continuing for 28 characters.
    formattedText.SetFontStyle(FontStyles.Italic, 28, 28)

    ' Draw the formatted text string to the DrawingContext of the control.
    drawingContext.DrawText(formattedText, New Point(10, 0))
End Sub

Unidad de medida del tamaño de fuenteFont Size Unit of Measure

Al igual que Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) con otros FormattedText objetos de texto en aplicaciones, el objeto utiliza píxeles independientes del dispositivo como unidad de medida.As with other text objects in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) applications, the FormattedText object uses device-independent pixels as the unit of measure. Sin embargo, la mayoría de las aplicaciones Win32 utilizan puntos como unidad de medida.However, most Win32 applications use points as the unit of measure. Si desea utilizar el texto de Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) visualización en unidades de puntos en las aplicaciones, debe convertir las unidades independientes del dispositivo (1/96 de pulgada por unidad) en puntos.If you want to use display text in units of points in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) applications, you need to convert device-independent units (1/96th inch per unit) to points. En el ejemplo de código siguiente se muestra cómo realizar esta conversión.The following code example shows how to perform this conversion.

// The font size is calculated in terms of points -- not as device-independent pixels.
formattedText.SetFontSize(36 * (96.0 / 72.0), 0, 5);
' The font size is calculated in terms of points -- not as device-independent pixels.
formattedText.SetFontSize(36 * (96.0 / 72.0), 0, 5)

Convertir texto con formato a una geometríaConverting Formatted Text to a Geometry

Puede convertir texto con Geometry formato en objetos, lo que le permite crear otros tipos de texto visualmente interesante.You can convert formatted text into Geometry objects, allowing you to create other types of visually interesting text. Por ejemplo, podría Geometry crear un objeto basado en el contorno de una cadena de texto.For example, you could create a Geometry object based on the outline of a text string.

Esquema de texto que usa un pincel de degradado lineal

En los ejemplos siguientes se muestran varias maneras de crear efectos visuales interesantes modificando el trazo, el relleno y el resaltado del texto convertido.The following examples illustrate several ways of creating interesting visual effects by modifying the stroke, fill, and highlight of converted text.

Texto con colores diferentes para relleno y trazo

Texto con pincel de imagen aplicado a trazo

Texto con pincel de imagen aplicado al trazo y resaltado

Cuando el texto Geometry se convierte en un objeto, ya no es una colección de caracteres: no se pueden modificar los caracteres de la cadena de texto.When text is converted to a Geometry object, it is no longer a collection of characters—you cannot modify the characters in the text string. Sin embargo, puede afectar a la apariencia del texto convertido modificando sus propiedades de trazo y relleno.However, you can affect the appearance of the converted text by modifying its stroke and fill properties. El trazo se refiere al contorno del texto convertido; el relleno es el área dentro del contorno del texto convertido.The stroke refers to the outline of the converted text; the fill refers to the area inside the outline of the converted text. Para obtener más información, consulte Crear texto con contorno.For more information, see Create Outlined Text.

También puede convertir texto con PathGeometry formato en un objeto y utilizar el objeto para resaltar el texto.You can also convert formatted text to a PathGeometry object, and use the object for highlighting the text. Por ejemplo, podría aplicar una PathGeometry animación al objeto para que la animación siga el contorno del texto con formato.For example, you could apply an animation to the PathGeometry object so that the animation follows the outline of the formatted text.

En el ejemplo siguiente se muestra el PathGeometry texto con formato que se ha convertido en un objeto.The following example shows formatted text that has been converted to a PathGeometry object. Una elipse animada sigue la ruta de los trazos del texto representado.An animated ellipse follows the path of the strokes of the rendered text.

Esfera que sigue la geometría de trayecto de texto
Esfera que sigue la geometría de trayecto de textoSphere following the path geometry of text

Para obtener más información, consulte How to: Create a PathGeometry Animation for Text (Cómo: Crear una animación PathGeometry para texto).For more information, see How to: Create a PathGeometry Animation for Text.

Puede crear otros usos interesantes para el texto PathGeometry con formato una vez que se ha convertido en un objeto.You can create other interesting uses for formatted text once it has been converted to a PathGeometry object. Por ejemplo, puede recortar vídeo para que se muestre dentro de él.For example, you can clip video to display inside it.

Vídeo mostrándose en la geometría de trayecto de texto

Migración de Win32Win32 Migration

Las características FormattedText del texto de dibujo son similares a las características de la función DrawText de Win32.The features of FormattedText for drawing text are similar to the features of the Win32 DrawText function. Para los desarrolladores que migran desde la API de Win32, en la Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF)tabla siguiente se enumeran los indicadores DrawText de Win32 y el equivalente aproximado en .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)Windows Presentation Foundation (WPF).

Marca DrawTextDrawText flag Equivalente de WPFWPF equivalent NotasNotes
DT_BOTTOMDT_BOTTOM Height Utilice Height la propiedad para calcular una posición 'y' de Win32 DrawText adecuada.Use the Height property to compute an appropriate Win32 DrawText 'y' position.
DT_CALCRECTDT_CALCRECT Height, WidthHeight, Width Utilice Height las Width propiedades y para calcular el rectángulo de salida.Use the Height and Width properties to calculate the output rectangle.
DT_CENTERDT_CENTER TextAlignment Utilice TextAlignment la propiedad con Centerel valor establecido en .Use the TextAlignment property with the value set to Center.
DT_EDITCONTROLDT_EDITCONTROL NoneNone No se requiere.Not required. El ancho del espacio y la representación de la última línea son los mismos que en el control de edición de marcos.Space width and last line rendering are the same as in the framework edit control.
DT_END_ELLIPSISDT_END_ELLIPSIS Trimming Utilice Trimming la propiedad CharacterEllipsiscon el valor .Use the Trimming property with the value CharacterEllipsis.

Se WordEllipsis usa para obtener DT_END_ELLIPSIS Win32 con puntos suspensivos finales DT_WORD_ELIPSIS: en este caso, los puntos suspensivos de caracteres solo se producen en palabras que no caben en una sola línea.Use 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_TABSDT_EXPAND_TABS NoneNone No se requiere.Not required. Las tabulaciones se expanden automáticamente a cada 4 ems, que es, aproximadamente, el ancho de 8 caracteres independientes del lenguaje.Tabs are automatically expanded to stops every 4 ems, which is approximately the width of 8 language-independent characters.
DT_EXTERNALLEADINGDT_EXTERNALLEADING NoneNone No se requiere.Not required. El espacio externo siempre se incluye en el interlineado.External leading is always included in line spacing. Utilice LineHeight la propiedad para crear un interlineado definido por el usuario.Use the LineHeight property to create user-defined line spacing.
DT_HIDEPREFIXDT_HIDEPREFIX NoneNone No compatible.Not supported. Quite el '&' de la FormattedText cadena antes de construir el objeto.Remove the '&' from the string before constructing the FormattedText object.
DT_LEFTDT_LEFT TextAlignment Esta es la alineación del texto predeterminada.This is the default text alignment. Utilice TextAlignment la propiedad con Leftel valor establecido en .Use the TextAlignment property with the value set to Left. (Solo WPF)(WPF only)
DT_MODIFYSTRINGDT_MODIFYSTRING NoneNone No compatible.Not supported.
DT_NOCLIPDT_NOCLIP VisualClip El recorte no se realiza automáticamente.Clipping does not happen automatically. Si desea recortar texto, VisualClip utilice la propiedad.If you want to clip text, use the VisualClip property.
DT_NOFULLWIDTHCHARBREAKDT_NOFULLWIDTHCHARBREAK NoneNone No compatible.Not supported.
DT_NOPREFIXDT_NOPREFIX NoneNone No se requiere.Not required. El carácter '&' en las cadenas siempre se trata como un carácter normal.The '&' character in strings is always treated as a normal character.
DT_PATHELLIPSISDT_PATHELLIPSIS NoneNone Utilice Trimming la propiedad WordEllipsiscon el valor .Use the Trimming property with the value WordEllipsis.
DT_PREFIXDT_PREFIX NoneNone No compatible.Not supported. Si desea utilizar guiones bajos para el texto, como SetTextDecorations una clave de acelerador o un vínculo, utilice el método.If you want to use underscores for text, such as an accelerator key or link, use the SetTextDecorations method.
DT_PREFIXONLYDT_PREFIXONLY NoneNone No compatible.Not supported.
DT_RIGHTDT_RIGHT TextAlignment Utilice TextAlignment la propiedad con Rightel valor establecido en .Use the TextAlignment property with the value set to Right. (Solo WPF)(WPF only)
DT_RTLREADINGDT_RTLREADING FlowDirection Establezca la propiedad FlowDirection en RightToLeft.Set the FlowDirection property to RightToLeft.
DT_SINGLELINEDT_SINGLELINE NoneNone No se requiere.Not required. FormattedTextlos objetos se comportan como un MaxTextWidth control de línea única, a menos que se establezca la propiedad o el texto contenga un retorno de carro/alimentación de línea (CR/LF).FormattedText objects behave as a single line control, unless either the MaxTextWidth property is set or the text contains a carriage return/line feed (CR/LF).
DT_TABSTOPDT_TABSTOP NoneNone No se admite para las posiciones de tabulación definidas por el usuario.No support for user-defined tab stop positions.
DT_TOPDT_TOP Height No se requiere.Not required. La justificación superior es el valor predeterminado.Top justification is the default. Otros valores de posicionamiento vertical Height se pueden definir mediante la propiedad para calcular una posición 'y' de Win32 DrawText adecuada.Other vertical positioning values can be defined by using the Height property to compute an appropriate Win32 DrawText 'y' position.
DT_VCENTERDT_VCENTER Height Utilice Height la propiedad para calcular una posición 'y' de Win32 DrawText adecuada.Use the Height property to compute an appropriate Win32 DrawText 'y' position.
DT_WORDBREAKDT_WORDBREAK NoneNone No se requiere.Not required. La ruptura de FormattedText palabras ocurre automáticamente con los objetos.Word breaking happens automatically with FormattedText objects. No se puede deshabilitar.You cannot disable it.
DT_WORD_ELLIPSISDT_WORD_ELLIPSIS Trimming Utilice Trimming la propiedad WordEllipsiscon el valor .Use the Trimming property with the value WordEllipsis.

Consulte tambiénSee also