Dibujar texto con formatoDrawing Formatted Text

Este tema proporciona información general de las características de la FormattedText 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

La FormattedText objeto permite dibujar texto de varias líneas, en el que cada carácter en el texto puede aplicarse 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 FormattedTextText displayed using FormattedText object
Texto mostrado mediante un método FormattedTextDisplayed text using FormattedText method

Nota

Para aquellos desarrolladores que migran desde la API Win32Win32, la tabla en la sección migración de Win32 enumera las marcas DrawText de Win32Win32 y el equivalente aproximado en Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF).For those developers migrating from the Win32Win32 API, the table in the Win32 Migration section lists the Win32Win32 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, la TextBlock deberían usar el elemento cuando se requiere, como una frase breve en compatibilidad con texto limitado un interfaz de usuario (UI)user interface (UI).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 usar cuando se requiere la compatibilidad de texto mínima.Label can be used when minimal text support is required. Para obtener más información, consulte Documentos en WPF.For more information, see Documents in WPF.

El FormattedText objeto proporciona características que de formato de texto mayor Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) controles de texto y puede ser útil en casos donde probablemente prefiera usar 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, el FormattedText objeto es útil para crear texto DrawingVisual-objetos derivados.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 formato, llame a la FormattedText constructor para crear un FormattedText 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.

Use la MaxTextWidth 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. Use la MaxTextHeight propiedad para restringir el texto a un alto específico.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 mediante un objeto FormattedTextText displayed using FormattedText object
Texto visualizado donde aparecen el ajuste automático de línea y los puntos suspensivosDisplayed text showing wordwrapping and ellipsis

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 tanto la SetFontSize y SetForegroundBrush métodos para cambiar el formato de los cinco primeros 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 de código siguiente se crea un FormattedText de objeto y, a continuación, se aplica a 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 con otros objetos de texto en Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) aplicaciones, la FormattedText objeto utiliza píxeles independientes del dispositivo como la 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 de Win32Win32 utilizan puntos como unidad de medida.However, most Win32Win32 applications use points as the unit of measure. Si desea utilizar el texto visualizado en unidades de puntos en las aplicaciones de Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF), deberá convertir unidades independientes de dispositivo (1/96 de pulgada por unidad)device-independent units (1/96th inch per unit) a 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 unidades independientes de dispositivo (1/96 de pulgada por unidad)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 el texto con formato en Geometry 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 crear un Geometry objeto basado en el esquema de una cadena de texto.For example, you could create a Geometry object based on the outline of a text string.

Contorno al texto mediante un pincel de degradado linealText outline using a linear gradient brush
Esquema de texto que usa un pincel de degradado linealText outline using a linear gradient brush

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 trazoText with different colors for fill and stroke
Ejemplo de configuración de relleno y trazo en diferentes coloresExample of setting stroke and fill to different colors

Texto con pincel de imagen aplicado a trazoText with image brush applied to stroke
Ejemplo de pincel de imagen aplicado al trazoExample of an image brush applied to the stroke

Texto con pincel de imagen aplicado a trazoText with image brush applied to stroke
Ejemplo de pincel de imagen aplicado al trazo y el resaltadoExample of an image brush applied to the stroke and highlight

Cuando el texto se convierte en un Geometry de objeto, ya no es una colección de caracteres, no se puede 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 formato a un PathGeometry de objetos 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 animación a la PathGeometry para que la animación sigue el contorno del texto con formato de objeto.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 texto con formato que se ha convertido en un PathGeometry 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 textoSphere following the path geometry of text
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 con formato una vez que se ha convertido en un PathGeometry 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 textoVideo displaying in the path geometry of text
Vídeo mostrándose en la geometría de trayecto de textoVideo displaying in the path geometry of text

Migración de Win32Win32 Migration

Las características de FormattedText para dibujar texto son similares a las características de la Win32Win32 función DrawText.The features of FormattedText for drawing text are similar to the features of the Win32Win32 DrawText function. Para aquellos desarrolladores que migran desde la API de Win32Win32, en la tabla siguiente se enumeran las marcas DrawText de Win32Win32 y el equivalente aproximado en Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF).For those developers migrating from the Win32Win32 API, the following table lists the Win32Win32 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 Use la Height propiedad para calcular una adecuada Win32Win32 posición DrawText 'y'.Use the Height property to compute an appropriate Win32Win32 DrawText 'y' position.
DT_CALCRECTDT_CALCRECT Height, WidthHeight, Width Use la Height y Width propiedades para calcular el rectángulo de salida.Use the Height and Width properties to calculate the output rectangle.
DT_CENTERDT_CENTER TextAlignment Use la TextAlignment propiedad con el valor establecido en Center.Use the TextAlignment property with the value set to Center.
DT_EDITCONTROLDT_EDITCONTROL NingunaNone No es necesario.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 Use la Trimming propiedad con el valor CharacterEllipsis.Use the Trimming property with the value CharacterEllipsis.

Use WordEllipsis para obtener Win32Win32 DT_END_ELLIPSIS con DT_WORD_ELIPSIS finalizar puntos suspensivos: en este caso, el botón de puntos suspensivos caracteres solo se produce en palabras que no caben en una sola línea.Use WordEllipsis to get Win32Win32 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 NingunaNone No es necesario.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 NingunaNone No es necesario.Not required. El espacio externo siempre se incluye en el interlineado.External leading is always included in line spacing. Use la LineHeight propiedad que se va a crear el interlineado definido por el usuario.Use the LineHeight property to create user-defined line spacing.
DT_HIDEPREFIXDT_HIDEPREFIX NingunaNone No se admite.Not supported. Quite el signo '&' de la cadena antes de construir el FormattedText 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. Use la TextAlignment propiedad con el valor establecido en Left.Use the TextAlignment property with the value set to Left. (Solo WPF)(WPF only)
DT_MODIFYSTRINGDT_MODIFYSTRING NingunaNone No se admite.Not supported.
DT_NOCLIPDT_NOCLIP VisualClip El recorte no se realiza automáticamente.Clipping does not happen automatically. Si desea recortar texto, use la VisualClip propiedad.If you want to clip text, use the VisualClip property.
DT_NOFULLWIDTHCHARBREAKDT_NOFULLWIDTHCHARBREAK NingunaNone No se admite.Not supported.
DT_NOPREFIXDT_NOPREFIX NingunaNone No es necesario.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 NingunaNone Use la Trimming propiedad con el valor WordEllipsis.Use the Trimming property with the value WordEllipsis.
DT_PREFIXDT_PREFIX NingunaNone No se admite.Not supported. Si desea utilizar caracteres de subrayado para el texto, como una tecla de aceleración o vínculo, use la SetTextDecorations método.If you want to use underscores for text, such as an accelerator key or link, use the SetTextDecorations method.
DT_PREFIXONLYDT_PREFIXONLY NingunaNone No se admite.Not supported.
DT_RIGHTDT_RIGHT TextAlignment Use la TextAlignment propiedad con el valor establecido en Right.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 NingunaNone No es necesario.Not required. FormattedTextlos objetos se comportan como un control de línea única, a menos que ya sea el MaxTextWidth se establece la propiedad o el texto contiene un retorno de carro/avance (CR/LF) de línea.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 NingunaNone 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 es necesario.Not required. La justificación superior es el valor predeterminado.Top justification is the default. Otros valores de posición verticales pueden definirse mediante el Height propiedad para calcular una adecuada Win32Win32 posición DrawText 'y'.Other vertical positioning values can be defined by using the Height property to compute an appropriate Win32Win32 DrawText 'y' position.
DT_VCENTERDT_VCENTER Height Use la Height propiedad para calcular una adecuada Win32Win32 posición DrawText 'y'.Use the Height property to compute an appropriate Win32Win32 DrawText 'y' position.
DT_WORDBREAKDT_WORDBREAK NingunaNone No es necesario.Not required. Separación de palabras se realiza automáticamente con FormattedText objetos.Word breaking happens automatically with FormattedText objects. No se puede deshabilitar.You cannot disable it.
DT_WORD_ELLIPSISDT_WORD_ELLIPSIS Trimming Use la Trimming propiedad con el valor WordEllipsis.Use the Trimming property with the value WordEllipsis.

Vea tambiénSee Also

FormattedText
Documentos en WPFDocuments in WPF
Tipografía en WPFTypography in WPF
Crear texto con contornoCreate Outlined Text
How to: Create a PathGeometry Animation for Text (Cómo: Crear una animación PathGeometry para texto).How to: Create a PathGeometry Animation for Text