Disegnare del testo formattato

In questo argomento viene fornita una panoramica delle funzionalità dell'oggetto FormattedText. Questo oggetto fornisce un controllo di basso livello per il disegno di testo nelle applicazioni Windows Presentation Foundation (WPF).

Panoramica della tecnologia

L'oggetto FormattedText consente di disegnare testo a più righe, in cui ogni carattere del testo può essere formattato singolarmente. Nell'esempio seguente viene illustrato il testo con diversi formati applicati.

Annotazioni

Per gli sviluppatori che migrano dall'API Win32, la tabella nella sezione Migrazione Win32 elenca i flag DrawText Win32 e il corrispettivo approssimativo in Windows Presentation Foundation (WPF).

Motivi per l'uso di testo formattato

WPF include più controlli per disegnare testo sullo schermo. Ogni controllo è destinato a uno scenario diverso e ha un proprio elenco di funzionalità e limitazioni. In generale, l'elemento TextBlock deve essere usato quando è necessario un supporto di testo limitato, ad esempio una breve frase in un'interfaccia utente. Label può essere usato quando è necessario un supporto di testo minimo. Per maggiori informazioni, vedere i Documenti in WPF.

L'oggetto FormattedText offre funzionalità di formattazione del testo maggiori rispetto ai controlli di testo windows Presentation Foundation (WPF) e può essere utile nei casi in cui si desidera utilizzare il testo come elemento decorativo. Per altre informazioni, vedere la sezione seguente Conversione di testo formattato in una geometria.

Inoltre, l'oggetto FormattedText è utile per creare oggetti derivati da DrawingVisualorientati al testo. DrawingVisual è una classe di disegno leggera usata per eseguire il rendering di forme, immagini o testo. Per altre informazioni, vedere hit test usando DrawingVisuals Sample.

Utilizzo dell'oggetto FormattedText

Per creare testo formattato, chiamare il costruttore FormattedText per creare un oggetto FormattedText. Dopo aver creato la stringa di testo formattata iniziale, è possibile applicare un intervallo di stili di formattazione.

Utilizzare la proprietà MaxTextWidth per vincolare il testo a una larghezza specifica. Il testo andrà a capo automaticamente per evitare di superare la larghezza specificata. Utilizzare la proprietà MaxTextHeight per vincolare il testo a un'altezza specifica. Il testo mostrerà un'ellissi "…" per il testo che supera l'altezza specificata.

È possibile applicare più stili di formattazione a uno o più caratteri. Ad esempio, è possibile chiamare i metodi SetFontSize e SetForegroundBrush per modificare la formattazione dei primi cinque caratteri nel testo.

Nell'esempio di codice seguente viene creato un oggetto FormattedText e quindi vengono applicati diversi stili di formattazione al testo.

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

Unità di misura per la dimensione del carattere

Come per altri oggetti di testo nelle applicazioni Windows Presentation Foundation (WPF), l'oggetto FormattedText usa pixel indipendenti dal dispositivo come unità di misura. Tuttavia, la maggior parte delle applicazioni Win32 usa punti come unità di misura. Se si vuole usare il testo visualizzato in unità di punti nelle applicazioni Windows Presentation Foundation (WPF), è necessario convertire unità indipendenti dal dispositivo (1/96° pollice per unità) in punti. Nell'esempio di codice seguente viene illustrato come eseguire questa conversione.

// 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)

Conversione di testo formattato in una geometria

È possibile convertire testo formattato in oggetti Geometry, consentendo di creare altri tipi di testo visivamente interessante. Ad esempio, è possibile creare un oggetto Geometry in base alla struttura di una stringa di testo.

Gli esempi seguenti illustrano diversi modi per creare effetti visivi interessanti modificando il tratto, il riempimento e l'evidenziazione del testo convertito.

Quando il testo viene convertito in un oggetto Geometry, non è più una raccolta di caratteri. Non è possibile modificare i caratteri nella stringa di testo. Tuttavia, è possibile influire sull'aspetto del testo convertito modificandone le proprietà di tratto e riempimento. Il tratto fa riferimento alla struttura del testo convertito; il riempimento fa riferimento all'area all'interno della struttura del testo convertito. Per altre informazioni, vedere Creare testo delineato.

È anche possibile convertire il testo formattato in un oggetto PathGeometry e utilizzare l'oggetto per evidenziare il testo. Ad esempio, è possibile applicare un'animazione all'oggetto PathGeometry in modo che l'animazione segua la struttura del testo formattato.

Nell'esempio seguente viene illustrato il testo formattato convertito in un oggetto PathGeometry. Un'ellisse animata segue il percorso dei tratti del testo renderizzato.

Sfera che segue la geometria del percorso testuale

Per ulteriori informazioni, vedere Come creare un'animazione PathGeometry per il testo.

È possibile creare altri usi interessanti per il testo formattato dopo che è stato convertito in un oggetto PathGeometry. Ad esempio, è possibile ritagliare i video per visualizzarli al suo interno.

Migrazione Win32

Le caratteristiche di FormattedText per il testo di disegno sono simili alle caratteristiche della funzione DrawText Win32. Per gli sviluppatori che eseguono la migrazione dall'API Win32, nella tabella seguente sono elencati i flag DrawText Win32 e l'equivalente approssimativo in Windows Presentation Foundation (WPF).

Opzione DrawText	Equivalente WPF	Note
DT_BOTTOM	Height	Usare la proprietà Height per calcolare una posizione di DrawText 'y' Win32 appropriata.
DT_CALCRECT	Height, Width	Usare le proprietà Height e Width per calcolare il rettangolo di uscita.
DT_CENTER	TextAlignment	Utilizzare la proprietà TextAlignment con il valore impostato su Center.
DT_EDITCONTROL	Nessuno	Non obbligatorio. La larghezza dello spazio e il rendering dell'ultima riga sono uguali a quelli del controllo di modifica del framework.
DT_END_ELLIPSIS	Trimming	Utilizzare la proprietà Trimming con il valore CharacterEllipsis. Usare WordEllipsis per ottenere DT_END_ELLIPSIS Win32 con puntini di sospensione DT_WORD_ELIPSIS fine. In questo caso, i puntini di sospensione dei caratteri si verificano solo su parole che non rientrano in una singola riga.
DT_EXPAND_TABS	Nessuno	Non obbligatorio. Le schede vengono espanse automaticamente fino a fermate ogni 4 em, ovvero approssimativamente la larghezza di 8 caratteri indipendenti dalla lingua.
DT_EXTERNALLEADING	Nessuno	Non obbligatorio. L'interlinea esterna è sempre inclusa nella spaziatura delle righe. Utilizzare la proprietà LineHeight per creare l'interlinea definita dall'utente.
DT_HIDEPREFIX	Nessuno	Non supportato. Rimuovere '&' dalla stringa prima di costruire l'oggetto FormattedText.
DT_LEFT	TextAlignment	Si tratta dell'allineamento del testo predefinito. Utilizzare la proprietà TextAlignment con il valore impostato su Left. (solo WPF)
DT_MODIFYSTRING	Nessuno	Non supportato.
DT_NOCLIP	VisualClip	Il ritaglio non viene eseguito automaticamente. Se si desidera ritagliare testo, utilizzare la proprietà VisualClip.
DT_NOFULLWIDTHCHARBREAK	Nessuno	Non supportato.
DT_NOPREFIX	Nessuno	Non obbligatorio. Il carattere '&' nelle stringhe viene sempre considerato come un carattere normale.
DT_PATHELLIPSIS	Nessuno	Utilizzare la proprietà Trimming con il valore WordEllipsis.
DT_PREFIX	Nessuno	Non supportato. Se si desidera utilizzare caratteri di sottolineatura per il testo, ad esempio un tasto di scelta rapida o un collegamento, usare il metodo SetTextDecorations.
DT_PREFIXONLY	Nessuno	Non supportato.
DT_RIGHT	TextAlignment	Utilizzare la proprietà TextAlignment con il valore impostato su Right. (solo WPF)
DT_RTLREADING	FlowDirection	Impostare la proprietà FlowDirection su RightToLeft.
DT_SINGLELINE	Nessuno	Non obbligatorio. FormattedText oggetti si comportano come un controllo di una sola riga, a meno che la proprietà MaxTextWidth non sia impostata o che il testo contenga un ritorno a capo/avanzamento riga (CR/LF).
DT_TABSTOP	Nessuno	Nessun supporto per le posizioni di tabulazione definite dall'utente.
DT_TOP	Height	Non obbligatorio. La giustificazione principale è l'impostazione predefinita. È possibile definire altri valori di posizionamento verticale usando la proprietà Height per calcolare una posizione DrawText 'y' Win32 appropriata.
DT_VCENTER	Height	Usare la proprietà Height per calcolare una posizione di DrawText 'y' Win32 appropriata.
DT_WORDBREAK	Nessuno	Non obbligatorio. La divisione delle parole avviene automaticamente con gli oggetti FormattedText. Non è possibile disabilitarla.
DT_PAROLA_ELLISSI	Trimming	Utilizzare la proprietà Trimming con il valore WordEllipsis.

Vedere anche

• FormattedText
• Documenti in WPF
• Tipografia del testo in WPF
• Creare testo con contorno
• Procedura: Creare un'animazione di PathGeometry per il testo