Dibujar texto con formato

Actualización: noviembre 2007

En este tema se proporciona información general sobre las características del objeto FormattedText. Este objeto proporciona control de bajo nivel para dibujar texto en aplicaciones de Windows Presentation Foundation (WPF).

Este tema contiene las secciones siguientes.

• Información general sobre la tecnología
• Utilizar el objeto FormattedText
• Migración de Win32
• Temas relacionados

Información general sobre la tecnología

El objeto FormattedText permite dibujar texto con varias líneas, en el que se puede dar formato a cada carácter individualmente. En el ejemplo siguiente se muestra texto con varios formatos.

Texto mostrado mediante el método FormattedText

Nota

Para los programadores que migran desde API de Win32, la tabla de la sección Migración de Win32 enumera los marcadores DrawText de Win32 y el equivalente aproximado en Windows Presentation Foundation (WPF).

Razones para utilizar el texto con formato

WPF incluye varios controles para dibujar texto en la pantalla. Cada control se destina a un escenario diferente y tiene su propia lista de características y limitaciones. En general, el elemento TextBlock se debe usar cuando se necesita una compatibilidad de texto limitada, como una frase breve en una interfaz de usuario (UI). Label se puede usar cuando se necesita una compatibilidad de texto mínima. Para obtener más información, vea Documentos en Windows Presentation Foundation.

El objeto FormattedText proporciona más características de formato de texto que los controles de texto de Windows Presentation Foundation (WPF) y puede ser útil en casos donde se desea utilizar el texto como elemento decorativo. Para obtener más información, vea la sección siguiente Convertir texto con formato en una geometría.

Además, el objeto FormattedText es útil para crear objetos orientados a texto derivados de DrawingVisual. DrawingVisual es una clase de dibujo ligera que se utiliza para representar formas, imágenes o texto. Para obtener más información, vea Ejemplo Hit Test Using DrawingVisuals.

Utilizar el objeto FormattedText

Para crear texto con formato, llame al constructor FormattedText para crear un objeto FormattedText. Una vez creada la cadena de texto con formato inicial, puede aplicarle varios estilos de formato.

Utilice la propiedad MaxTextWidth para restringir el texto a un ancho específico. El texto se ajustará automáticamente para evitar superar el ancho especificado. Utilice la propiedad MaxTextHeight para restringir el texto a un alto específico. El texto mostrará puntos suspensivos, "…". para el texto que supera el alto especificado.

Texto mostrado al que se ha aplicado el ajuste de línea y los puntos suspensivos

Puede aplicar varios estilos de formato a uno o más caracteres. Por ejemplo, podría llamar a los métodos SetFontSize y SetForegroundBrush para cambiar el formato de los cinco primeros caracteres del texto.

En el ejemplo de código siguiente se crea un objeto FormattedText y, a continuación, se aplican varios estilos de formato al texto.

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));
}

Unidad de medida del tamaño de fuente

Como sucede con otros objetos de texto en las aplicaciones de Windows Presentation Foundation (WPF), el objeto FormattedText utiliza los píxeles independientes del dispositivo como unidad de medida. Sin embargo, la mayoría de las aplicaciones de Win32 utilizan los puntos como unidad de medida. Si desea utilizar el texto visualizado en unidades de puntos en las aplicaciones de Windows Presentation Foundation (WPF), es preciso convertir los unidades independientes de dispositivo (1/96 de pulgada por unidad) en puntos. En el ejemplo de código siguiente se muestra cómo realizar esta conversión.

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

Convertir el texto con formato en una geometría

Puede convertir el texto con formato en objetos Geometry, lo que permite crear otros tipos de texto visualmente interesante. Por ejemplo, podría crear un objeto Geometry basado en el contorno de una cadena de texto.

Aplicación de un contorno al texto mediante 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.

Ejemplo de cómo establecer el trazo y el relleno en diferentes colores
Ejemplo de un pincel de imagen aplicado al trazo
Ejemplo de un pincel de imagen aplicado al trazo y al resaltado

Cuando se convierte el texto en un objeto Geometry, deja de ser una colección de caracteres; no se pueden modificar los caracteres de la cadena de texto. Sin embargo, se puede cambiar la apariencia del texto convertido modificando sus propiedades de trazo y relleno. El trazo se refiere al contorno del texto convertido; el relleno se refiere al área situada dentro del contorno del texto convertido. Para obtener más información, vea Cómo: Crear texto con contorno.

También puede convertir el texto con formato en un objeto PathGeometry y utiliza el objeto para resaltar el texto. Por ejemplo, puede aplicar una animación al objeto PathGeometry para que la animación siga el contorno del texto con formato.

En el ejemplo siguiente se muestra texto con formato convertido en un objeto PathGeometry. Una elipse animada sigue el trazado de los trazos del texto representado.

Esfera que sigue la geometría de trazado del texto

Para obtener más información, vea Cómo: Crear una animación de PathGeometry para texto.

Puede crear otros usos interesantes para el texto con formato una vez convertido en un objeto PathGeometry. Por ejemplo, puede mostrar en él un clip de vídeo. Para obtener más información, vea Demo Video Text.

Vídeo mostrado en la geometría de trazado del texto

Migración de Win32

Las características de FormattedText para dibujar texto son similares a las de la función DrawText de Win32. Para los programadores que migran desde la API de Win32, se enumeran en la tabla siguiente los marcadores de DrawText de Win32 y su equivalente aproximado en Windows Presentation Foundation (WPF).

Marcador de DrawText	Equivalente de WPF	Notas
DT_BOTTOM	Height	Utilice la propiedad Height para calcular la posición de 'y' correcta de DrawText de Win32.
DT_CALCRECT	Height, Width	Utilice las propiedades Height y Width para calcular el rectángulo de salida.
DT_CENTER	TextAlignment	Utilice la propiedad TextAlignment con el valor establecido en Center.
DT_EDITCONTROL	Ninguno	No se necesita. El ancho del espacio y la representación de la última línea son iguales que en el control de edición del marco de trabajo.
DT_END_ELLIPSIS	Trimming	Utilice la propiedad Trimming con el valor CharacterEllipsis. Utilice WordEllipsis para obtener DT_END_ELLIPSIS de Win32 con los puntos suspensivos finales de DT_WORD_ELIPSIS; en este caso, los puntos suspensivos sólo se muestran en las palabras que no caben en una sola línea.
DT_EXPAND_TABS	Ninguno	No se necesita. Las tabulaciones se expanden automáticamente a cada 4 ems, que es aproximadamente el ancho de 8 caracteres independientes del lenguaje.
DT_EXTERNALLEADING	Ninguno	No se necesita. El espacio externo siempre se incluye en el interlineado. Utilice la propiedad LineHeight para crear el interlineado definido por el usuario.
DT_HIDEPREFIX	Ninguno	No se admite. Quite el signo '&' de la cadena antes de construir el objeto FormattedText.
DT_LEFT	TextAlignment	Ésta es la alineación predeterminada del texto. Utilice la propiedad TextAlignment con el valor establecido en Left. (Sólo WPF)
DT_MODIFYSTRING	Ninguno	No se admite.
DT_NOCLIP	VisualClip	El recorte no se realiza automáticamente. Si desea recortar texto, utilice la propiedad VisualClip.
DT_NOFULLWIDTHCHARBREAK	Ninguno	No se admite.
DT_NOPREFIX	Ninguno	No se necesita. El carácter '&' en las cadenas se trata siempre como un carácter normal.
DT_PATHELLIPSIS	Ninguno	Utilice la propiedad Trimming con el valor WordEllipsis.
DT_PREFIX	Ninguno	No se admite. Si desea utilizar el subrayado para el texto, como en una tecla de aceleración o vínculo, utilice el método SetTextDecorations.
DT_PREFIXONLY	Ninguno	No se admite.
DT_RIGHT	TextAlignment	Utilice la propiedad TextAlignment con el valor establecido en Right. (Sólo WPF)
DT_RTLREADING	FlowDirection	Establezca la propiedad FlowDirection en RightToLeft.
DT_SINGLELINE	Ninguno	No se requiere. Los objetos FormattedText se comportan como un control de una sola línea, a menos que se establezca la propiedad MaxTextWidth o que el texto contenga un retorno de carro o salto de línea.
DT_TABSTOP	Ninguno	No se admiten las posiciones de tabulación definidas por el usuario.
DT_TOP	Height	No se necesita. La justificación superior es la predeterminada. Se pueden definir otros valores de posición vertical utilizando la propiedad Height para calcular la posición apropiada de 'y' en un DrawText de Win32.
DT_VCENTER	Height	Utilice la propiedad Height para calcular la posición de 'y' correcta de DrawText de Win32.
DT_WORDBREAK	Ninguno	No se necesita. La ruptura de palabras se efectúa automáticamente en los objetos FormattedText. No se puede deshabilitar.
DT_WORD_ELLIPSIS	Trimming	Utilice la propiedad Trimming con el valor WordEllipsis.

Vea también

Tareas

Demo Video Text

Cómo: Crear texto con contorno

Conceptos

Documentos en Windows Presentation Foundation

Tipografía en Windows Presentation Foundation

Cómo: Crear una animación de PathGeometry para texto

Referencia

FormattedText