Disegno di testo formattato

In questo argomento vengono forniti dei cenni preliminari sulle funzionalità dell'oggetto FormattedText. Questo oggetto fornisce un controllo di basso livello per il disegno di testo nelle applicazioni Windows Presentation Foundation (WPF).

Nel presente argomento sono contenute le seguenti sezioni.

• Cenni preliminari sulla tecnologia
• Utilizzo dell'oggetto FormattedText
• Migrazione Win32
• Argomenti correlati

Cenni preliminari sulla tecnologia

L'oggetto FormattedText consente di creare testo su più righe, in cui ogni carattere può essere formattato singolarmente. Nell'esempio seguente viene mostrato un testo a cui sono stati applicati diversi formati.

Testo visualizzato con il metodo FormattedText

Nota
Per gli sviluppatori che eseguono la migrazione dall'API Win32, nella tabella della sezione Migrazione Win32 sono elencati i flag DrawText di Win32 e gli elementi corrispondenti di Windows Presentation Foundation (WPF).

Motivi dell'utilizzo del testo formattato

WPF include più controlli per la creazione di testo sullo schermo. Ogni controllo è destinato a uno scenario diverso e dispone di un proprio elenco di funzionalità e limitazioni. In genere, è opportuno utilizzare l'elemento TextBlock quando è necessario un supporto limitato del testo, ad esempio una breve frase in un'user interface (UI). Quando è necessario un supporto minimo del testo, è possibile utilizzare Label. Per ulteriori informazioni, vedere Documenti in WPF.

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

Inoltre, l'oggetto FormattedText è utile per la creazione di oggetti derivati DrawingVisual orientati al testo. DrawingVisual è una classe di disegno semplificata utilizzata per il rendering di forme, immagini o testo. Per ulteriori informazioni, vedere Esempio di hit test mediante DrawingVisual (la pagina potrebbe essere in inglese).

Utilizzo dell'oggetto FormattedText

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

Utilizzare la proprietà MaxTextWidth per specificare dei limiti in relazione alla larghezza del testo. Il testo andrà a capo automaticamente per evitare di superare la larghezza specificata. Utilizzare la proprietà MaxTextHeight per specificare dei limiti in relazione all'altezza del testo. Saranno visualizzati dei puntini di sospensione ("…") laddove il testo superi l'altezza specificata.

Testo visualizzato con ritorno a capo automatico e puntini di sospensione

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

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

        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

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

Unità di misura della dimensione del carattere

Come per altri oggetti di testo nelle applicazioni Windows Presentation Foundation (WPF), l'oggetto FormattedText utilizza come unità di misura Device Independent Pixel. Tuttavia, la maggior parte delle applicazioni Win32 utilizza i punti come unità di misura. Se si desidera utilizzare il testo visualizzato in una scala di punti nelle applicazioni Windows Presentation Foundation (WPF), sarà necessario convertire i device-independent units (1/96th inch per unit) in punti. Nell'esempio di codice seguente viene illustrata l'esecuzione di 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 il testo formattato in oggetti Geometry, per creare altri tipi di testo dall'aspetto accattivante. Ad esempio, è possibile creare un oggetto Geometry in base alla struttura di una stringa di testo.

Struttura di testo con pennello sfumato lineare

Negli esempi seguenti vengono illustrate varie modalità di creazione di effetti visivi interessanti tramite la modifica del tratto, del riempimento e dell'evidenziazione del testo convertito.

Esempio di impostazione di tratto e riempimento in colori diversi

Esempio di pennello di immagine applicato al tratto

Esempio di tratto con immagine applicato al tratto e all'evidenziazione

Se il testo viene convertito in un oggetto Geometry, non costituisce più un insieme di caratteri. Di conseguenza, non è possibile modificare i caratteri della stringa di testo. È tuttavia possibile intervenire sull'aspetto del testo convertito modificandone le proprietà di tratto e 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 ulteriori informazioni, vedere Procedura: creare testo con contorni.

È possibile inoltre convertire il testo formattato in un oggetto PathGeometry e utilizzarlo per evidenziare il testo. Ad esempio, all'oggetto PathGeometry potrebbe essere applicata un'animazione che segua la struttura del testo formattato.

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

Sfera che segue la geometria del percorso del testo

Per ulteriori informazioni, vedere Procedura: creare animazioni PathGeometry per il testo.

È possibile creare altri utilizzi interessanti del testo formattato dopo averlo convertito in un oggetto PathGeometry. Ad esempio, è possibile ritagliare un video da visualizzare all'interno del testo.

Video visualizzato nella geometria del percorso del testo

Migrazione Win32

Le funzionalità di FormattedText per la creazione del testo sono simili a quelle della funzione DrawText di Win32. Per gli sviluppatori che eseguono la migrazione dall'API Win32, nella tabella riportata di seguito sono elencati i flag DrawText di Win32 e i corrispondenti elementi di Windows Presentation Foundation (WPF).

Flag DrawText	Elemento corrispondente WPF	Note
DT_BOTTOM	Height	Utilizzare la proprietà Height per calcolare una posizione 'y' di DrawText Win32 appropriata.
DT_CALCRECT	Height, Width	Utilizzare le proprietà Height e Width per calcolare il rettangolo di output.
DT_CENTER	TextAlignment	Utilizzare la proprietà TextAlignment con il valore impostato su Center.
DT_EDITCONTROL	Nessuno	Non obbligatoria 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. Utilizzare WordEllipsis per ottenere DT_END_ELLIPSIS e i puntini di sospensione finali DT_WORD_ELIPSIS di Win32. In questo caso, vengono troncati solo i caratteri delle parole che non rientrano in una sola riga.
DT_EXPAND_TABS	Nessuno	Non obbligatoria Le tabulazioni vengono espanse automaticamente per consentire tabulazioni ogni 4 em, corrispondenti all'incirca a una larghezza di 8 caratteri indipendenti dalla lingua.
DT_EXTERNALLEADING	Nessuno	Non obbligatoria L'interlinea esterna è sempre inclusa nell'interlinea. Utilizzare la proprietà LineHeight per creare un'interlinea definita dall'utente.
DT_HIDEPREFIX	Nessuno	Non supportato. Rimuovere '&' dalla stringa prima di costruire l'oggetto FormattedText.
DT_LEFT	TextAlignment	Impostazione predefinita per l'allineamento del testo. 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. Per ritagliare il testo, utilizzare la proprietà VisualClip.
DT_NOFULLWIDTHCHARBREAK	Nessuno	Non supportato.
DT_NOPREFIX	Nessuno	Non obbligatoria Il carattere '&' nelle stringhe viene sempre considerato come 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 un testo, ad esempio un tasto di scelta rapida o un collegamento, utilizzare 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 obbligatoria. Gli oggetti FormattedText si comportano come un controllo a riga singola, a meno che non sia impostata la proprietà MaxTextWidth o il testo non contenga un ritorno a capo/avanzamento riga (CR/LF).
DT_TABSTOP	Nessuno	Nessun supporto per le posizioni delle tabulazioni definite dall'utente.
DT_TOP	Height	Non obbligatoria Il testo è giustificato nella parte superiore per impostazione predefinita. Gli altri valori di posizionamento verticale possono essere definiti utilizzando la proprietà Height per calcolare una posizione 'y' di DrawText Win32 appropriata.
DT_VCENTER	Height	Utilizzare la proprietà Height per calcolare una posizione 'y' di DrawText Win32 appropriata.
DT_WORDBREAK	Nessuno	Non obbligatoria Le parole vengono interrotte automaticamente con gli oggetti FormattedText. Non è possibile disabilitarlo.
DT_WORD_ELLIPSIS	Trimming	Utilizzare la proprietà Trimming con il valore WordEllipsis.

Vedere anche

Attività

Procedura: creare testo con contorni

Riferimenti

FormattedText

Concetti

Documenti in WPF

Funzionalità tipografiche di WPF

Procedura: creare animazioni PathGeometry per il testo