Disegno di 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 su più righe, in cui ogni carattere del testo può essere formattato singolarmente. L'esempio seguente mostra un testo a cui sono stati applicati diversi formati.

Nota

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

Motivi per l'uso del testo formattato

WPF include più controlli per disegnare testo sullo schermo. Ogni controllo è destinato a uno scenario diverso e dispone di 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 altre informazioni, vedere 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 del testo formattato in una geometria.

Inoltre, l'oggetto FormattedText è utile per la creazione di oggetti derivati da testo orientati al DrawingVisualtesto. DrawingVisual è una classe di disegno leggera utilizzata per eseguire il rendering di forme, immagini o testo. Per altre informazioni, vedere Esempio di hit test mediante DrawingVisual.

Uso dell'oggetto FormattedText

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

Utilizzare la MaxTextWidth proprietà per vincolare il testo a una larghezza specifica. Il testo andrà a capo automaticamente per evitare di superare la larghezza specificata. Utilizzare la MaxTextHeight proprietà per vincolare il testo a un'altezza specifica. Saranno visualizzati dei puntini di sospensione ("...") nel caso in cui il testo superi l'altezza specificata.

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

Nell'esempio di codice seguente viene creato un FormattedText oggetto 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 delle dimensioni del carattere

Come con 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 del testo formattato in una geometria

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

Gli esempi seguenti illustrano diverse modalità di creazione di effetti visivi interessanti tramite la modifica del tratto, del riempimento e dell'evidenziazione del testo convertito.

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

È anche possibile convertire il testo formattato in un PathGeometry oggetto e usare 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 PathGeometry oggetto . Un'ellisse animata segue il percorso dei tratti del testo di cui è stato eseguito il rendering.

Sfera che segue la geometria del percorso del testo

Per altre informazioni, vedere Procedura: Creare animazioni PathGeometry per il testo.

È possibile creare altri usi interessanti per il testo formattato dopo che è stato convertito in un PathGeometry oggetto . Ad esempio, è possibile ritagliare video da visualizzare all'interno del testo.

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

Flag DrawText	Elemento corrispondente in WPF	Note
DT_BOTTOM	Height	Usare la Height proprietà per calcolare una posizione 'y' di DrawText Win32 appropriata.
DT_CALCRECT	Height, Width	Utilizzare le Height proprietà e Width per calcolare il rettangolo di output.
DT_CENTER	TextAlignment	Usare la TextAlignment proprietà con il valore impostato su Center.
DT_EDITCONTROL	None	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	Usare la Trimming proprietà con il valore CharacterEllipsis. Usa 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	None	Non obbligatorio. Le tabulazioni vengono espanse automaticamente per interrompersi ogni 4 em, all'incirca a una larghezza di 8 caratteri indipendenti dalla lingua.
DT_EXTERNALLEADING	None	Non obbligatorio. L'interlinea esterna è sempre inclusa nell'interlinea. Utilizzare la LineHeight proprietà per creare l'interlinea definita dall'utente.
DT_HIDEPREFIX	None	Non supportato. Rimuovere '&' dalla stringa prima di costruire l'oggetto FormattedText .
DT_LEFT	TextAlignment	Impostazione predefinita per l'allineamento del testo. Usare la TextAlignment proprietà con il valore impostato su Left. (solo WPF).
DT_MODIFYSTRING	None	Non supportato.
DT_NOCLIP	VisualClip	Il ritaglio non viene eseguito automaticamente. Se si desidera ritagliare testo, utilizzare la VisualClip proprietà .
DT_NOFULLWIDTHCHARBREAK	None	Non supportato.
DT_NOPREFIX	None	Non obbligatorio. Il carattere "&" nelle stringhe viene sempre considerato un carattere normale.
DT_PATHELLIPSIS	None	Usare la Trimming proprietà con il valore WordEllipsis.
DT_PREFIX	None	Non supportato. Se si desidera usare caratteri di sottolineatura per il testo, ad esempio un tasto di scelta rapida o un collegamento, usare il SetTextDecorations metodo .
DT_PREFIXONLY	None	Non supportato.
DT_RIGHT	TextAlignment	Usare la TextAlignment proprietà con il valore impostato su Right. (solo WPF).
DT_RTLREADING	FlowDirection	Impostare la proprietà FlowDirection su RightToLeft.
DT_SINGLELINE	None	Non obbligatorio. FormattedText gli oggetti si comportano come un controllo a riga singola, a meno che la MaxTextWidth proprietà non sia impostata o che il testo contenga un ritorno a capo/avanzamento riga (CR/LF).
DT_TABSTOP	None	Nessun supporto per le posizioni delle tabulazioni definite dall'utente.
DT_TOP	Height	Non obbligatorio. Il testo è giustificato nella parte superiore per impostazione predefinita. È possibile definire altri valori di posizionamento verticale usando la Height proprietà per calcolare una posizione DrawText 'y' Win32 appropriata.
DT_VCENTER	Height	Usare la Height proprietà per calcolare una posizione 'y' di DrawText Win32 appropriata.
DT_WORDBREAK	None	Non obbligatorio. L'interruzione delle parole avviene automaticamente con FormattedText gli oggetti . Non è possibile disabilitare questa impostazione.
DT_WORD_ELLIPSIS	Trimming	Usare la Trimming proprietà con il valore WordEllipsis.

Vedi anche

• FormattedText
• Documenti in WPF
• Funzionalità tipografiche di WPF
• Creare testo con contorni
• Procedura: Creare animazioni PathGeometry per il testo