Click or drag to resize
CanvasTextLayout Class
A cached, drawable piece of formatted text which can combine different fonts, colors etc.
Inheritance Hierarchy
SystemObject
  Microsoft.Graphics.Canvas.TextCanvasTextLayout

Namespace:  Microsoft.Graphics.Canvas.Text
Assembly:  Microsoft.Graphics.Canvas (in Microsoft.Graphics.Canvas.dll) Version: 0.0.0.0
Syntax
C#
public sealed class CanvasTextLayout : IDisposable

The CanvasTextLayout type exposes the following members.

Constructors
  NameDescription
Public methodCanvasTextLayout
Initializes a new instance of the CanvasTextLayout class.
Top
Properties
  NameDescription
Public propertyClusterMetrics
Gets an array of metrics describing each cluster.
Public propertyCustomTrimmingSign
Gets or sets a custom trimming sign.
Public propertyDefaultFontFamily
Specifies the font family name for ranges of the layout that don't have an explicitly specified font family name.
Public propertyDefaultFontSize
Specifies the font size for ranges of the layout without an explicitly specified font size.
Public propertyDefaultFontStretch
Specifies the font stretch for ranges of the layout without an explicitly specified font stretch.
Public propertyDefaultFontStyle
Specifies the font style for ranges of the layout without an explicitly specified font style.
Public propertyDefaultFontWeight
Specifies the font weight for ranges of the layout without an explicitly specified font weight.
Public propertyDefaultLocaleName
Specifies the locale name for ranges of the layout without an explicitly specified locale name.
Public propertyDevice
Gets the device associated with this text layout.
Public propertyDirection
Specifies the direction in which the text is read.
Public propertyDrawBounds
Gets the bounds of the parts of the text that would get drawn.
Public propertyHorizontalAlignment
Specifies the horizontal paragraph alignment.
Public propertyIncrementalTabStop
Specifies the incremental tab stop position.
Public propertyLastLineWrapping
Specifies whether or not the last word on the last line is wrapped.
Public propertyLayoutBounds
Gets the bounds of the parts of the text that align to the layout.
Public propertyLayoutBoundsIncludingTrailingWhitespace
Gets a rectangle describing the bounds of text, plus any trailing whitespace.
Public propertyLineCount
Gets the number of lines in the text layout.
Public propertyLineMetrics
Gets an array of metrics describing each line.
Public propertyLineSpacing
Negative values use default line spacing; non-negative values specify the line height.
Public propertyLineSpacingBaseline
Specifies the distance from top of line to baseline. A reasonable ratio to lineSpacing is 80 percent.
Public propertyLineSpacingMode
[Win10] Specifies how lines are spaced apart.
Public propertyMaximumBidiReorderingDepth
Gets the maximum reordering depth for direction changes of bi-directional text.
Public propertyOpticalAlignment
Specifies the optical margin aligment for the text layout.
Public propertyOptions
Specifies text drawing options.
Public propertyRequestedSize
Specifies the requested size.
Public propertyTrimmingDelimiter
A character used as the delimiter that signals the beginning of the portion of text to be preserved.
Public propertyTrimmingDelimiterCount
A value that indicates how many occurrences of the delimiter, counted from the end of the text, are allowed before trimming is desired.
Public propertyTrimmingGranularity
Specifies the granularity used to trim text overflowing the layout box.
Public propertyTrimmingSign
Specifies the type of trimming sign used, when text is drawn outside a text layout's requested size extents.
Public propertyVerticalAlignment
Specifies the vertical paragraph alignment.
Public propertyVerticalGlyphOrientation
Specifies the orientation of glyphs when a vertical reading direction is used.
Public propertyWordWrapping
Specifies word wrapping behavior.
Top
Methods
  NameDescription
Public methodDispose
Releases all resources used by the CanvasTextLayout.
Public methodDrawToTextRenderer(ICanvasTextRenderer, Vector2)
Draws this text layout to an application-defined text renderer.
Public methodDrawToTextRenderer(ICanvasTextRenderer, Single, Single)
Draws this text layout to an application-defined text renderer.
Public methodGetBrush
Gets the brush associated with a character index in the text layout.
Public methodGetCaretPosition(Int32, Boolean)
Gets position where the caret (text cursor) would be, given the current text position and caret direction.
Public methodGetCaretPosition(Int32, Boolean, CanvasTextLayoutRegion)
Gets position where the caret (text cursor) would be, given the current text position and caret direction.
Public methodGetCharacterRegions
Gets an array of descriptions of the range of text.
Public methodGetCustomBrush
Gets the custom brush associated with a character index in the text layout.
Public methodGetFontFamily
Gets the font family of the character at the specified position.
Public methodGetFontSize
Gets the font size for the character at the specified position.
Public methodGetFontStretch
Gets the font stretch for the character at the specified position.
Public methodGetFontStyle
Gets the font style for the character at the specified position.
Public methodGetFontWeight
Gets the font weight for the character at the specified position.
Public methodGetFormatChangeIndices
Gets an array of position indices at which the text format changes.
Public methodStatic memberGetGlyphOrientationTransform
Gets a transform matrix to use when drawing a glyph run.
Public methodGetInlineObject
Gets the inline object for the character at the position specified.
Public methodGetLeadingCharacterSpacing
Gets the the spacing before the character specified, in reading order.
Public methodGetLocaleName
Specifies the locale name for the character at the specified position.
Public methodGetMinimumCharacterAdvance
Gets the minimum advance of the character specified.
Public methodGetMinimumLineLength
Gets the minimum possible width/height the layout can be set to, without any emergency breakings between the characters of whole words.
Public methodGetPairKerning
Gets whether pair kerning is used for the character at the position specified.
Public methodGetStrikethrough
Gets whether the character at the specified position has strikethrough.
Public methodGetTrailingCharacterSpacing
Gets the spacing after the character specified, in reading order.
Public methodGetTypography
Gets the typography features that affect the character at the position specified.
Public methodGetUnderline
Gets whether the character at the specified position is underlined.
Public methodHitTest(Vector2)
Gets whether the point overlaps with any text in the text layout.
Public methodHitTest(Single, Single)
Gets whether the point overlaps with any text in the text layout.
Public methodHitTest(Vector2, CanvasTextLayoutRegion)
Gets whether the point overlaps with any text in the text layout.
Public methodHitTest(Single, Single, CanvasTextLayoutRegion)
Gets whether the point overlaps with any text in the text layout.
Public methodHitTest(Vector2, CanvasTextLayoutRegion, Boolean)
Gets whether the point overlaps with any text in the text layout.
Public methodHitTest(Single, Single, CanvasTextLayoutRegion, Boolean)
Gets whether the point overlaps with any text in the text layout.
Public methodSetBrush
Sets the brush associated with a group of characters in the text layout.
Public methodSetCharacterSpacing
Sets the spacing between characters.
Public methodSetColor
Sets the color associated with a group of characters in the text layout.
Public methodSetCustomBrush
Sets the custom brush associated with a group of characters in the text layout.
Public methodSetFontFamily
Sets the font family of the specified group of characters.
Public methodSetFontSize
Sets the font size of the specified group of characters.
Public methodSetFontStretch
Sets the font stretch of the specified group of characters.
Public methodSetFontStyle
Sets the font style of the specified group of characters.
Public methodSetFontWeight
Sets the font weight of the specified group of characters.
Public methodSetInlineObject
Sets the inline object for a specified group of characters.
Public methodSetLocaleName
Sets the local name of the specified group of characters.
Public methodSetPairKerning
Sets whether pair kerning is used for the group of characters specified.
Public methodSetStrikethrough
Applies strikethrough formatting to the specified group of characters.
Public methodSetTypography
Sets the typography features that affect a specified group of characters.
Public methodSetUnderline
Applies underline formatting to the specified group of characters.
Top
Remarks

Use CanvasTextLayout to display rich text combining different formatting options, and to query the size and layout of such text after it has been wordwrapped.

If you are going to draw the same piece of text more than once, CanvasTextLayout can be faster than DrawText Overload, because it can reuse layout computations rather than repeating them every time the text is drawn.

When using Direct2D interop, this Win2D class corresponds to the Direct2D interface IDWriteTextLayout2 on Windows 8.1, and IDWriteTextLayout3 on Windows 10.

Examples
How to create a CanvasTextLayout:
var format = new CanvasTextFormat();

var textLayout = new CanvasTextLayout("A piece of text", format, layoutWidth, layoutHeight);
How to draw a CanvasTextLayout:
using (var ds = renderTarget.CreateDrawingSession())
{
    ds.DrawTextLayout(textLayout, 100, 200, Colors.White); // White text is drawn at (100, 200)
}
See Also