Drawing Formatted Text

Este tópico fornece uma visão geral dos recursos do objeto FormattedText. Esse objeto fornece controle de baixo nível para desenhar texto em aplicativos Windows Presentation Foundation (WPF).

Este tópico contém as seguintes seções.

• Visão Geral da Tecnologia
• Usando o objeto FormattedText
• Migração a partir de Win32
• Tópicos relacionados

Visão Geral da Tecnologia

O objeto FormattedText permite que você desenhe texto de várias linhas, no qual cada caractere no texto pode ser formatado individualmente. O exemplo a seguir mostra texto que possui diversos formatos aplicados a ele.

Texto exibido usando método FormattedText

Observação:
Para os desenvolvedores migrando das Win32 API, a tabela a Migração do Win32 seção lista o Win32 Sinalizadores DrawText e o equivalente aproximado no Windows Presentation Foundation (WPF).

Motivos para se usar formatação de texto

WPF inclui vários controles para desenhar texto na tela. Cada controle é almejado a um cenário diferente e tem sua própria lista de características e limitações. Em geral, a TextBlock elemento deve ser usado quando o suporte limitado de texto é necessário, por exemplo, uma breve frase em um interface do usuário (UI). Label pode ser usado quando a quantidade mínima de texto de suporte é necessária. Para obter mais informações, consulte Documentos em Windows Presentation Foundation.

The FormattedText objeto oferece recursos de formatação de texto maior Windows Presentation Foundation (WPF) controles de texto e pode ser útil em casos onde você deseja usar texto sistema autônomo um elemento decorativo. Para obter mais informações, consulte a seção a seguir Converter texto em uma geometria com formatação.

Além disso, a FormattedText objeto é útil para a criação orientada a texto DrawingVisual-objetos derivados. DrawingVisual é uma classe de desenho leve que é usada para processar as formas, imagens ou texto. Para obter mais informações, consulte Teste usando o exemplo de DrawingVisuals de visitas.

Usando o objeto FormattedText

Para criar texto formatado, chame o construtor FormattedText para criar um objeto FormattedText. Depois de criar a sequência de caracteres de texto formatado inicial, você pode aplicar uma variedade de estilos de formatação.

Use a propriedade MaxTextWidth para restringir o texto a uma largura específica. O texto será disposto automaticamente para evitar exceder a largura especificada. Use a propriedade MaxTextHeight para restringir o texto a uma altura específica. O texto exibirá reticências, "…" para o texto que ultrapassar a altura especificada.

Texto exibido mostrando quebra de linha e reticências

Você pode aplicar diversos estilos de formatação a um ou mais caracteres. Por exemplo, você poderia chamar tanto o método SetFontSize quanto o método SetForegroundBrush para alterar a formatação dos cinco primeiros caracteres no texto.

O exemplo de código a seguir cria um objeto FormattedText e aplica vários estilos de formatação ao 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));
}

Unidade de medida do tamanho da fonte

Como com outros objetos de texto em aplicativos Windows Presentation Foundation (WPF), o objeto FormattedText usa pixels independente de dispositivo como a unidade de medida. No entanto, a maioria dos aplicativos Win32 usam pontos como unidade de medida. Se você quiser usar texto de exibição em unidades de pontos em aplicativos Windows Presentation Foundation (WPF), precisará converter de unidades independentes de dispositivo (1/96 polegada por unidade) para pontos. O exemplo de código a seguir mostra como fazer essa conversão.

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

Convertendo texto formatado em uma geometria

Você pode converter texto formatado em objetos Geometry, permitindo que você crie outros tipos de texto visualmente interessante. Por exemplo, você pode criar um objeto Geometry com base no contorno de um string de texto.

Contorno do texto usando um pincel de gradiente linear

Os exemplos a seguir ilustram diversas formas de criar efeitos visuais interessantes modificando o traço, preenchimento e destaque do texto convertido.

Exemplo de definição de traço e preenchimento com diferentes cores.

Exemplo de um pincel de imagem aplicado ao traço

Exemplo de um pincel de imagem aplicado ao traço e destaque.

Quando o texto é convertido em um objeto Geometry ele não é mais um conjunto de caracteres — você não pode modificar os caracteres na sequência de texto. No entanto, você pode afetar a aparência do texto convertido modificando suas propriedades de "pincelada" e de preenchimento. A "pincelada", ou "traço", refere-se ao contorno do texto convertido; o preenchimento refere-se a área dentro o contorno do texto convertido. Para obter mais informações, consulte Como: Desenhar a borda de um texto.

Você pode também converter texto formatado para um objeto PathGeometry e usar o objeto para realçar o texto. Por exemplo, você poderia aplicar uma animação ao objeto PathGeometry de forma que a animação siga o contorno do texto formatado.

O exemplo a seguir mostra texto formatado que foi convertido em um objeto PathGeometry. Uma elipse animada segue o caminho das pinceladas do texto renderizado.

Esfera seguindo a geometria de caminho do texto

Para obter mais informações, consulte Como: Create a PathGeometry Animation for Text.

Você pode criar outros usos interessantes para texto formatado depois que ele for convertido para um objeto PathGeometry. Por exemplo, você pode recortar vídeos para exibi-los dentro do texto. Para obter mais informações, consulte Demonstração de texto de vídeo.

Vídeo em exibição na geometria de caminho do texto

Migração a partir de Win32

Os recursos de FormattedText para desenho de texto são semelhantes aos recursos da função DrawText de Win32. Para os desenvolvedores migrando a partir da API Win32, a seguinte tabela lista as flags de DrawText em Win32 e o equivalente aproximado em Windows Presentation Foundation (WPF).

Flag DrawText	Equivalente em WPF	Anotações
DT_BOTTOM	Height	Use a propriedade Height para calcular uma posição adequada para o 'y' do DrawText em Win32.
DT_CALCRECT	Height, Width	Use as propriedades Height e Width para calcular o retângulo de saída.
DT_CENTER	TextAlignment	Use a propriedade TextAlignment com o valor definido como Center.
DT_EDITCONTROL	Nenhum	Não necessário. Largura de espaço e renderização da última linha são iguais àqueles do controle de edição do framework.
DT_END_ELLIPSIS	Trimming	Use a propriedade Trimming com o valor CharacterEllipsis. Use WordEllipsis para obter Win32 DT_END_ELLIPSIS com reticências finais DT_WORD_ELIPSIS — nesse caso, reticências de caractere ocorrem apenas em palavras que não cabem em uma única linha.
DT_EXPAND_TABS	Nenhum	Não necessário. As guias são automaticamente expandidas para paradas a cada 4 ems, que é aproximadamente a largura de 8 caracteres independentes de idioma.
DT_EXTERNALLEADING	Nenhum	Não necessário. Espa?amento externo é sempre incluído no espaçamento de linha. Use a propriedade LineHeight para criar espaçamento definido pelo usuário.
DT_HIDEPREFIX	Nenhum	Sem suporte. Remova o '&' da strings antes de construir o objeto FormattedText.
DT_LEFT	TextAlignment	Este é o alinhamento de texto padrão. Use a propriedade TextAlignment com o valor definido como Left. (Apenas em WPF)
DT_MODIFYSTRING	Nenhum	Sem suporte.
DT_NOCLIP	VisualClip	O recorte não acontece automaticamente. Se você quiser recortar texto, use a propriedade VisualClip.
DT_NOFULLWIDTHCHARBREAK	Nenhum	Sem suporte.
DT_NOPREFIX	Nenhum	Não necessário. O caractere '&' em strings é sempre tratado como um caractere normal.
DT_PATHELLIPSIS	Nenhum	Use a propriedade Trimming com o valor WordEllipsis.
DT_PREFIX	Nenhum	Sem suporte. Se você deseja usar caracteres sublinhados para texto, como uma tecla aceleradora ou link, use o método SetTextDecorations.
DT_PREFIXONLY	Nenhum	Sem suporte.
DT_RIGHT	TextAlignment	Use a propriedade TextAlignment com o valor definido como Right. (Apenas em WPF)
DT_RTLREADING	FlowDirection	Defina a propriedade FlowDirection como RightToLeft.
DT_SINGLELINE	Nenhum	Não necessário. FormattedText objetos se comportem sistema autônomo um controle de única linha, a menos que ambos sistema autônomo MaxTextWidth a propriedade é definida ou o texto contiver um retorno de carro/feed de linha (CR/LF).
DT_TABSTOP	Nenhum	Não há suporte para posições de parada de tabulação definidas pelo usuário.
DT_TOP	Height	Não necessário. Justificação superior é o padrão. Outros valores de posicionamento vertical podem ser definidos usando a propriedade Height para calcular uma posição apropriada de 'y' para DrawText em Win32.
DT_VCENTER	Height	Use a propriedade Height para calcular uma posição adequada para o 'y' do DrawText em Win32.
DT_WORDBREAK	Nenhum	Não necessário. Que de linha acontece automaticamente com objetos FormattedText. Não é possível desabilitá-la.
DT_WORD_ELLIPSIS	Trimming	Use a propriedade Trimming com o valor WordEllipsis.

Consulte também

Tarefas

Demonstração de texto de vídeo

Como: Desenhar a borda de um texto

Conceitos

Documentos em Windows Presentation Foundation

Tipografia em Windows Presentation Foundation

Como: Create a PathGeometry Animation for Text

Referência

FormattedText