Click or drag to resize
ICanvasTextRenderer Interface
An application-implemented interface for receiving detailed rendering information about text layouts.

Namespace:  Microsoft.Graphics.Canvas.Text
Assembly:  Microsoft.Graphics.Canvas (in Microsoft.Graphics.Canvas.dll) Version: 0.0.0.0
Syntax
C#
public interface ICanvasTextRenderer

The ICanvasTextRenderer type exposes the following members.

Properties
  NameDescription
Public propertyDpi
Gets the current DPI.
Public propertyPixelSnappingDisabled
Gets whether pixel snapping is disabled.
Public propertyTransform
Gets the transform with which text should be drawn.
Top
Methods
  NameDescription
Public methodDrawGlyphRun
Signals to the app that it should draw a sequence of identically-formatted text characters.
Public methodDrawInlineObject
Signals to the app that it should draw an inline object.
Public methodDrawStrikethrough
Signals to the app that it should draw a strikethrough.
Public methodDrawUnderline
Signals to the app that it should draw an underline.
Top
Remarks

Custom text renderers are used for a wide variety of purposes, such as

  • Querying the metrics of the font which is used when drawing a text layout
  • Arbitrarily choosing the transform at which individual glyphs are drawn
  • Controlling the visibility of certain glyphs
  • Applying different imaging effects to different glyphs within a layout
  • Stylizing strikethroughs and underlines

Why is this renderer needed for knowing which font is used while drawing a text layout? There's a very deliberate reason why you can't simply measure text using a text format alone, or even a text format plus a set of characters. That reason is font fallbacks.

The font face that will ultimately get used when you draw text actually depends on the text string itself, together with a multitude of other environmental properties. Sounds surprising, right? If you ask for, say, a glyph that isn't in the font specified in your layout's text format, Win2D will take advantage of DirectWrite's fallback logic and actually switch the font to one that has the glyph. This is great for making apps that work well on a wide variety of environments, but it also means the info in that text format is really just a list of 'suggestions'. It's not a guarantee of which font will get used.

It's impossible to make guarantees about what specific font face will be used to measure or draw some text, until you actually have the glyphs on hand that you're trying to operate on, and the exact context in which you're using them. This is where ICanvasTextRenderer comes in.

ICanvasTextRenderer provides a guaranteed way for an app to know what font face is being used for drawing a piece of text, and what the properties of that font face are. Apps may want to intercept DrawGlyphRun to learn about metrics for a piece of text, or adjust some details about the glyph run before passing the parameters on to DrawToTextRenderer Overload.

See Also