Stone_Red/docs-desktop
1
0
Fork 0
mirror of https://github.com/Stone-Red-Code/docs-desktop.git synced 2026-09-07 23:43:19 +02:00
Code Issues Packages Projects Releases Wiki Activity

Links: .NET Desktop - framework\wpf (#109)

Browse Source 
* Links: .NET Desktop - framework\wpf

* Apply suggestions from code review

Co-authored-by: Andy De George <[email protected]>
This commit is contained in:
David Coulter
2020-11-05 13:50:29 -08:00
committed by GitHub
co-authored by Andy De George
parent c1d6e1d23e
commit 674b773578
67 changed files with 657 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dotnet-desktop-guide/framework/wpf/advanced/drawing-formatted-text.md
+11 -2
View File
@@ -12,9 +12,11 @@ helpviewer_keywords:
ms.assetid: b1d851c1-331c-4814-9964-6fe769db6f1f
---
# Drawing Formatted Text
This topic provides an overview of the features of the <xref:System.Windows.Media.FormattedText> object. This object provides low-level control for drawing text in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications.
## Technology Overview
The <xref:System.Windows.Media.FormattedText> object allows you to draw multi-line text, in which each character in the text can be individually formatted. The following example shows text that has several formats applied to it.
![Text displayed using FormattedText object](./media/typography-in-wpf/text-formatted-linear-gradient.jpg)
@@ -23,6 +25,7 @@ This topic provides an overview of the features of the <xref:System.Windows.Medi
> For those developers migrating from the Win32 API, the table in the [Win32 Migration](#win32_migration) section lists the Win32 DrawText flags and the approximate equivalent in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)].
### Reasons for Using Formatted Text
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own list of features and limitations. In general, the <xref:System.Windows.Controls.TextBlock> element should be used when limited text support is required, such as a brief sentence in a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. <xref:System.Windows.Controls.Label> can be used when minimal text support is required. For more information, see [Documents in WPF](documents-in-wpf.md).
The <xref:System.Windows.Media.FormattedText> object provides greater text formatting features than [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] text controls, and can be useful in cases where you want to use text as a decorative element. For more information, see the following section [Converting Formatted Text to a Geometry](#converting_formatted_text).
@@ -30,6 +33,7 @@ This topic provides an overview of the features of the <xref:System.Windows.Medi
In addition, the <xref:System.Windows.Media.FormattedText> object is useful for creating text-oriented <xref:System.Windows.Media.DrawingVisual>-derived objects. <xref:System.Windows.Media.DrawingVisual> is a lightweight drawing class that is used to render shapes, images, or text. For more information, see [Hit Test Using DrawingVisuals Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Visual%20Layer/DrawingVisual).
## Using the FormattedText Object
To create formatted text, call the <xref:System.Windows.Media.FormattedText.%23ctor%2A> constructor to create a <xref:System.Windows.Media.FormattedText> object. Once you have created the initial formatted text string, you can apply a range of formatting styles.
Use the <xref:System.Windows.Media.FormattedText.MaxTextWidth%2A> property to constrain the text to a specific width. The text will automatically wrap to avoid exceeding the specified width. Use the <xref:System.Windows.Media.FormattedText.MaxTextHeight%2A> property to constrain the text to a specific height. The text will display an ellipsis, "…" for the text that exceeds the specified height.
@@ -44,13 +48,16 @@ This topic provides an overview of the features of the <xref:System.Windows.Medi
[!code-vb[FormattedTextSnippets#FormattedTextSnippets1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/FormattedTextSnippets/visualbasic/window1.xaml.vb#formattedtextsnippets1)]
### Font Size Unit of Measure
As with other text objects in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications, the <xref:System.Windows.Media.FormattedText> object uses device-independent pixels as the unit of measure. However, most Win32 applications use points as the unit of measure. If you want to use display text in units of points in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications, you need to convert device-independent units (1/96th inch per unit) to points. The following code example shows how to perform this conversion.
[!code-csharp[FormattedTextSnippets#FormattedTextSnippets2](~/samples/snippets/csharp/VS_Snippets_Wpf/FormattedTextSnippets/CSharp/Window1.xaml.cs#formattedtextsnippets2)]
[!code-vb[FormattedTextSnippets#FormattedTextSnippets2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/FormattedTextSnippets/visualbasic/window1.xaml.vb#formattedtextsnippets2)]
<a name="converting_formatted_text"></a>
### Converting Formatted Text to a Geometry
You can convert formatted text into <xref:System.Windows.Media.Geometry> objects, allowing you to create other types of visually interesting text. For example, you could create a <xref:System.Windows.Media.Geometry> object based on the outline of a text string.
![Text outline using a linear gradient brush](./media/typography-in-wpf/text-outline-linear-gradient.jpg)
@@ -72,14 +79,16 @@ This topic provides an overview of the features of the <xref:System.Windows.Medi
![Sphere following the path geometry of text](./media/drawing-formatted-text/sphere-following-geometry-path.gif)
Sphere following the path geometry of text
For more information, see [How to: Create a PathGeometry Animation for Text](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/ms743610(v=vs.100)).
For more information, see [How to: Create a PathGeometry Animation for Text](/previous-versions/dotnet/netframework-4.0/ms743610(v=vs.100)).
You can create other interesting uses for formatted text once it has been converted to a <xref:System.Windows.Media.PathGeometry> object. For example, you can clip video to display inside it.
![Video displaying in the path geometry of text](./media/drawing-formatted-text/video-displaying-text-path-geometry.png)
<a name="win32_migration"></a>
## Win32 Migration
The features of <xref:System.Windows.Media.FormattedText> for drawing text are similar to the features of the Win32 DrawText function. For those developers migrating from the Win32 API, the following table lists the Win32 DrawText flags and the approximate equivalent in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)].
|DrawText flag|WPF equivalent|Notes|
@@ -115,4 +124,4 @@ Sphere following the path geometry of text
- [Documents in WPF](documents-in-wpf.md)
- [Typography in WPF](typography-in-wpf.md)
- [Create Outlined Text](how-to-create-outlined-text.md)
- [How to: Create a PathGeometry Animation for Text](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/ms743610(v=vs.100))
- [How to: Create a PathGeometry Animation for Text](/previous-versions/dotnet/netframework-4.0/ms743610(v=vs.100))