Disegno di testo formattatoDrawing Formatted Text

In questo argomento viene fornita una panoramica delle funzionalità dell'oggetto FormattedText.This topic provides an overview of the features of the FormattedText object. che offre un controllo di basso livello per il disegno di testo nelle applicazioni Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF).This object provides low-level control for drawing text in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) applications.

Informazioni generali sulla tecnologiaTechnology Overview

L'oggetto FormattedText consente di creare testo su più righe, in cui ogni carattere del testo può essere formattato singolarmente.The FormattedText object allows you to draw multi-line text, in which each character in the text can be individually formatted. L'esempio seguente mostra un testo a cui sono stati applicati diversi formati.The following example shows text that has several formats applied to it.

Testo visualizzato usando l'oggetto 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 l'equivalente approssimativo in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF).For those developers migrating from the Win32 API, the table in the Win32 Migration section lists the Win32 DrawText flags and the approximate equivalent in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF).

Motivi per l'uso del testo formattatoReasons for Using Formatted Text

WPFWPF include più controlli per la creazione di testo sullo schermo.includes multiple controls for drawing text to the screen. Ogni controllo è destinato a uno scenario diverso e dispone di un proprio elenco di funzionalità e limitazioni.Each control is targeted to a different scenario and has its own list of features and limitations. In generale, l'elemento TextBlock deve essere utilizzato quando è necessario il supporto di testo limitato, ad esempio una breve frase in una interfaccia utenteuser interface (UI).In general, the TextBlock element should be used when limited text support is required, such as a brief sentence in a interfaccia utenteuser interface (UI). Label può essere utilizzato quando è richiesto un supporto di testo minimo.Label can be used when minimal text support is required. Per altre informazioni, vedere Documenti in WPF.For more information, see Documents in WPF.

L'oggetto FormattedText fornisce funzionalità di formattazione del testo maggiori rispetto ai controlli Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) testo e può essere utile nei casi in cui si desidera utilizzare il testo come elemento decorativo.The FormattedText object provides greater text formatting features than Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) text controls, and can be useful in cases where you want to use text as a decorative element. Per altre informazioni, vedere la sezione seguente Conversione del testo formattato in una geometria.For more information, see the following section Converting Formatted Text to a Geometry.

Inoltre, l'oggetto FormattedText è utile per la creazione di oggetti derivati da DrawingVisualtesto.In addition, the FormattedText object is useful for creating text-oriented DrawingVisual-derived objects. DrawingVisual è una classe di disegno semplificata utilizzata per il rendering di forme, immagini o testo.DrawingVisual is a lightweight drawing class that is used to render shapes, images, or text. Per altre informazioni, vedere Esempio di hit test mediante DrawingVisual.For more information, see Hit Test Using DrawingVisuals Sample.

Uso dell'oggetto FormattedTextUsing the FormattedText Object

Per creare un testo formattato, chiamare il costruttore FormattedText per creare un oggetto FormattedText.To create formatted text, call the FormattedText constructor to create a FormattedText object. Dopo aver creato la stringa di testo formattato iniziale, è possibile applicare una gamma di stili di formattazione.Once you have created the initial formatted text string, you can apply a range of formatting styles.

Utilizzare la proprietà MaxTextWidth per vincolare il testo a una larghezza specifica.Use the MaxTextWidth property to constrain the text to a specific width. Il testo andrà a capo automaticamente per evitare di superare la larghezza specificata.The text will automatically wrap to avoid exceeding the specified width. Utilizzare la proprietà MaxTextHeight per vincolare il testo a un'altezza specifica.Use the MaxTextHeight property to constrain the text to a specific height. Saranno visualizzati dei puntini di sospensione ("...") nel caso in cui il testo superi l'altezza specificata.The text will display an ellipsis, "…" for the text that exceeds the specified height.

Testo visualizzato con WordWrap e puntini di sospensione.

È possibile applicare vari stili di formattazione a uno o più caratteri.You can apply multiple formatting styles to one or more characters. È ad esempio possibile chiamare entrambi i metodi SetFontSize e SetForegroundBrush per modificare la formattazione dei primi cinque caratteri del testo.For example, you could call both the SetFontSize and SetForegroundBrush methods to change the formatting of the first five characters in the text.

Nell'esempio di codice seguente viene creato un oggetto FormattedText, quindi vengono applicati diversi stili di formattazione al testo.The following code example creates a FormattedText object and then applies several formatting styles to the text.

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 carattereFont Size Unit of Measure

Come per gli altri oggetti di testo nelle applicazioni Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF), l'oggetto FormattedText usa pixel indipendenti dal dispositivo come unità di misura.As with other text objects in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) applications, the FormattedText object uses device-independent pixels as the unit of measure. Tuttavia, la maggior parte delle applicazioni Win32 utilizza punti come unità di misura.However, most Win32 applications use points as the unit of measure. Se si vuole usare il testo visualizzato in unità di punti in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) applicazioni, è necessario convertire le unità indipendenti dal dispositivo (1/1/96 pollice per unità) in punti.If you want to use display text in units of points in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) applications, you need to convert device-independent units (1/96th inch per unit) to points. Nell'esempio di codice seguente viene illustrato come eseguire questa conversione.The following code example shows how to perform this conversion.

// 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 geometriaConverting Formatted Text to a Geometry

È possibile convertire il testo formattato in oggetti Geometry, consentendo di creare altri tipi di testo visivamente interessante.You can convert formatted text into Geometry objects, allowing you to create other types of visually interesting text. Ad esempio, è possibile creare un oggetto Geometry in base alla struttura di una stringa di testo.For example, you could create a Geometry object based on the outline of a text string.

Struttura di testo con pennello sfumato lineare

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.The following examples illustrate several ways of creating interesting visual effects by modifying the stroke, fill, and highlight of converted text.

Testo con colori diversi per tratto e riempimento

Testo con tratto con immagine applicato

Testo con pennello immagine applicato al tratto ed evidenziato

Quando il testo viene convertito in un oggetto Geometry, non è più una raccolta di caratteri, non è possibile modificare i caratteri nella stringa di testo.When text is converted to a Geometry object, it is no longer a collection of characters—you cannot modify the characters in the text string. Tuttavia, è possibile intervenire sull'aspetto del testo convertito modificandone le proprietà del tratto e del riempimento.However, you can affect the appearance of the converted text by modifying its stroke and fill properties. Il tratto fa riferimento alla struttura del testo convertito, mentre il riempimento fa riferimento all'area all'interno della struttura del testo convertito.The stroke refers to the outline of the converted text; the fill refers to the area inside the outline of the converted text. Per altre informazioni, vedere Creare testo con contorni.For more information, see Create Outlined Text.

È anche possibile convertire il testo formattato in un oggetto PathGeometry e usare l'oggetto per evidenziare il testo.You can also convert formatted text to a PathGeometry object, and use the object for highlighting the text. Ad esempio, è possibile applicare un'animazione all'oggetto PathGeometry in modo che l'animazione segua il contorno del testo formattato.For example, you could apply an animation to the PathGeometry object so that the animation follows the outline of the formatted text.

Nell'esempio seguente viene illustrato il testo formattato che è stato convertito in un oggetto PathGeometry.The following example shows formatted text that has been converted to a PathGeometry object. Un'ellisse animata segue il percorso dei tratti del testo di cui è stato eseguito il rendering.An animated ellipse follows the path of the strokes of the rendered text.

Sfera che segue la geometria del percorso del testo
Sfera che segue la geometria del percorso del testoSphere following the path geometry of text

Per altre informazioni, vedere Procedura: Creare animazioni PathGeometry per il testo.For more information, see How to: Create a PathGeometry Animation for Text.

È possibile creare altri usi interessanti per il testo formattato dopo che è stato convertito in un oggetto PathGeometry.You can create other interesting uses for formatted text once it has been converted to a PathGeometry object. Ad esempio, è possibile ritagliare video da visualizzare all'interno del testo.For example, you can clip video to display inside it.

Video visualizzato nella geometria del percorso del testo

Migrazione Win32Win32 Migration

Le funzionalità di FormattedText per il disegno del testo sono simili alle funzionalità della funzione DrawText di Win32.The features of FormattedText for drawing text are similar to the features of the Win32 DrawText function. Per gli sviluppatori che eseguono la migrazione dall'API Win32, nella tabella seguente sono elencati i flag DrawText di Win32 e l'equivalente approssimativo in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF).For those developers migrating from the Win32 API, the following table lists the Win32 DrawText flags and the approximate equivalent in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF).

Flag DrawTextDrawText flag Elemento corrispondente in WPFWPF equivalent NoteNotes
DT_BOTTOMDT_BOTTOM Height Utilizzare la proprietà Height per calcolare una posizione "y" di DrawText Win32 appropriata.Use the Height property to compute an appropriate Win32 DrawText 'y' position.
DT_CALCRECTDT_CALCRECT Height, WidthHeight, Width Utilizzare le proprietà Height e Width per calcolare il rettangolo di output.Use the Height and Width properties to calculate the output rectangle.
DT_CENTERDT_CENTER TextAlignment Utilizzare la proprietà TextAlignment con il valore impostato su Center.Use the TextAlignment property with the value set to Center.
DT_EDITCONTROLDT_EDITCONTROL nessunaNone Non obbligatorioNot required. La larghezza dello spazio e il rendering dell'ultima riga sono uguali a quelli del controllo di modifica del framework.Space width and last line rendering are the same as in the framework edit control.
DT_END_ELLIPSISDT_END_ELLIPSIS Trimming Utilizzare la proprietà Trimming con il valore CharacterEllipsis.Use the Trimming property with the value CharacterEllipsis.

Usare WordEllipsis per ottenere DT_END_ELLIPSIS Win32 con i puntini di sospensione DT_WORD_ELIPSIS, in questo caso i puntini di sospensione dei caratteri si verificano solo su parole che non rientrano in una singola riga.Use WordEllipsis to get Win32 DT_END_ELLIPSIS with DT_WORD_ELIPSIS end ellipsis—in this case, character ellipsis only occurs on words that do not fit on a single line.
DT_EXPAND_TABSDT_EXPAND_TABS nessunaNone Non obbligatorioNot required. Le tabulazioni vengono espanse automaticamente per interrompersi ogni 4 em, all'incirca a una larghezza di 8 caratteri indipendenti dalla lingua.Tabs are automatically expanded to stops every 4 ems, which is approximately the width of 8 language-independent characters.
DT_EXTERNALLEADINGDT_EXTERNALLEADING nessunaNone Non obbligatorioNot required. L'interlinea esterna è sempre inclusa nell'interlinea.External leading is always included in line spacing. Utilizzare la proprietà LineHeight per creare spaziatura riga definita dall'utente.Use the LineHeight property to create user-defined line spacing.
DT_HIDEPREFIXDT_HIDEPREFIX nessunaNone Non supportato.Not supported. Rimuovere ' &' dalla stringa prima di costruire l'oggetto FormattedText.Remove the '&' from the string before constructing the FormattedText object.
DT_LEFTDT_LEFT TextAlignment Impostazione predefinita per l'allineamento del testo.This is the default text alignment. Utilizzare la proprietà TextAlignment con il valore impostato su Left.Use the TextAlignment property with the value set to Left. (solo WPF).(WPF only)
DT_MODIFYSTRINGDT_MODIFYSTRING nessunaNone Non supportato.Not supported.
DT_NOCLIPDT_NOCLIP VisualClip Il ritaglio non viene eseguito automaticamente.Clipping does not happen automatically. Se si desidera ritagliare il testo, utilizzare la proprietà VisualClip.If you want to clip text, use the VisualClip property.
DT_NOFULLWIDTHCHARBREAKDT_NOFULLWIDTHCHARBREAK nessunaNone Non supportato.Not supported.
DT_NOPREFIXDT_NOPREFIX nessunaNone Non obbligatorioNot required. Il carattere "&" nelle stringhe viene sempre considerato un carattere normale.The '&' character in strings is always treated as a normal character.
DT_PATHELLIPSISDT_PATHELLIPSIS nessunaNone Utilizzare la proprietà Trimming con il valore WordEllipsis.Use the Trimming property with the value WordEllipsis.
DT_PREFIXDT_PREFIX nessunaNone Non supportato.Not supported. Se si desidera utilizzare caratteri di sottolineatura per il testo, ad esempio un tasto di scelta rapida o un collegamento, utilizzare il metodo SetTextDecorations.If you want to use underscores for text, such as an accelerator key or link, use the SetTextDecorations method.
DT_PREFIXONLYDT_PREFIXONLY nessunaNone Non supportato.Not supported.
DT_RIGHTDT_RIGHT TextAlignment Utilizzare la proprietà TextAlignment con il valore impostato su Right.Use the TextAlignment property with the value set to Right. (solo WPF).(WPF only)
DT_RTLREADINGDT_RTLREADING FlowDirection Impostare la proprietà FlowDirection su RightToLeft.Set the FlowDirection property to RightToLeft.
DT_SINGLELINEDT_SINGLELINE nessunaNone Non obbligatorioNot required. FormattedText gli oggetti si comportano come un controllo a riga singola, a meno che non sia impostata la proprietà MaxTextWidth o il testo contenga un ritorno a capo/avanzamento riga (CR/LF).FormattedText objects behave as a single line control, unless either the MaxTextWidth property is set or the text contains a carriage return/line feed (CR/LF).
DT_TABSTOPDT_TABSTOP nessunaNone Nessun supporto per le posizioni delle tabulazioni definite dall'utente.No support for user-defined tab stop positions.
DT_TOPDT_TOP Height Non obbligatorioNot required. Il testo è giustificato nella parte superiore per impostazione predefinita.Top justification is the default. È possibile definire altri valori di posizionamento verticale utilizzando la proprietà Height per calcolare una posizione "y" di DrawText Win32 appropriata.Other vertical positioning values can be defined by using the Height property to compute an appropriate Win32 DrawText 'y' position.
DT_VCENTERDT_VCENTER Height Utilizzare la proprietà Height per calcolare una posizione "y" di DrawText Win32 appropriata.Use the Height property to compute an appropriate Win32 DrawText 'y' position.
DT_WORDBREAKDT_WORDBREAK nessunaNone Non obbligatorioNot required. L'interruzione delle parole si verifica automaticamente con FormattedText oggetti.Word breaking happens automatically with FormattedText objects. Non è possibile disabilitare questa impostazione.You cannot disable it.
DT_WORD_ELLIPSISDT_WORD_ELLIPSIS Trimming Utilizzare la proprietà Trimming con il valore WordEllipsis.Use the Trimming property with the value WordEllipsis.

Vedere ancheSee also