IXRGlyphs (Compact 2013)

3/28/2014

This class represents a string of letters, characters, or symbols that is rendered with decorations that are defined by a specific font and style.

Syntax

class IXRGlyphs : public IXRFrameworkElement

Inheritance Hierarchy

IXRFrameworkElement

     IXRGlyphs

Methods

Thread Safety

Members of this class are thread-safe if you previously called IXRApplication::CreateHostFromXaml and supplied it with an XRWindowCreateParams structure that has AllowsMultipleThreadAccess set to true.

Remarks

IXRGlyphs is a class for rendering specific text and applying special decorations to it. IXRGlyphs works with text that has already been preformatted by a text-layout and writing-system engine. For all other scenarios, use IXRTextBlock.

IXRGlyphs does not have a content property, and you do not define glyphs by declaring text as the inner text of an IXRGlyphs object. Instead, you specify an individual glyph by setting two properties:

• IXRGlyphs::SetUnicodeString sets the string value to decorate. This value captures the Unicode string in an XML-compatible encoding.
• IXRGlyphs::SetIndices sets a string value that provides information about the set of glyph indices, or index values, that together describe the positions of blocks inside the region allocated for each character. This string uses a specialized format that references glyphs by their font-index order and, optionally, specifies values that define advance spacing and offset spacing.

Typically, glyphs are drawn on-screen by using both the set of glyph indices and the Unicode string. Graphics-rendering software displays the glyphs on-screen by using the set of glyph indices, whereas applications that either support text search or must internally read and process the original text use the underlying Unicode string.

To save time designing a glyph, you can learn which indices to set for an IXRGlyphs object by borrowing the indices for a glyph in the XML Paper Specification (XPS) document format. You can borrow (copy and paste) the XPS formatted output of a document-producing application such as Microsoft Office Word 2010. The XPS format produces packages that define the document. Included in the packaging is a XAML page that declares a FixedPage element by using the XPS schema (add the namespace for the XPS schema as follows: xmlns=https://schemas.microsoft.com/xps/2005/06). The XPS schema also contains a Glyphs element that you can use to determine the indices to set for your glyph. To reuse an XPS glyph in a XAML for Windows Embedded application, you open the package, find your FixedPage parts, extract the data defined in the Glyphs element, and paste the glyphs data into the source XAML or into the Set* methods in this class, such as the IXRGlyphs::SetIndices method.

If you want an IXRGlyphs object to be used only for rendering, you do not have to supply a value in IXRGlyphs::SetUnicodeString. For example, an application that includes its own text-formatting code, complex script-writing system code, and font-fallback implementation might generate such glyph objects while providing its own support for search, copy and paste, and accessibility.

If you want simple left-aligned text with no advanced or offset spacing between characters, you can supply a character string to SetUnicodeString, but you do not have to supply a value to SetIndices. This approach provides an optimization for XPS document size. In this case, the mapping from UTF-16 Unicode code point to glyph index must match the mappings specified in the font-character map table, and the advance width of the character must be exactly that specified in the font hmtx table, scaled linearly by the font size. Additionally, as with any glyphs element, all the text must be rendered by the font file that is specified by IXRGlyphs::GetFontUri. The following are specific limitations of a glyphs element that has a Unicode string but no glyph indices:

• Font fallback is not supported, and all characters must be supported by the specified font file.
• Code points beyond U+ffff (surrogate code points, which are used for many East Asian characters) cannot be displayed.
• Writing systems that require contextual substitution cannot be displayed. The following is a partial list of such systems:
  • Korean (Jamos)
  • Arabic (Farsi, Urdu, Syria, Thaana)
  • Hebrew
  • Thai, Lao, Khmer
  • Philippine (Tagalog, Hanunoo, Buhid, Tagbanwa)
  • Indic (Devangari, Bangla, Gurmukhi, Gujarati, Odia, Tamil, Telugu, Kannada, Malayalam, Sinhala)
  • Tibetan
  • Limbu
  • Ethiopic
  • Mongolian

In addition to the glyph information, you must always provide a font Universal Resource Identifier (URI) by calling IXRGlyphs::SetFontUri. There is no default or fallback characteristic that will provide a valid value. If you are defining glyphs in the source XAML for your application instead of using IXRGlyphs, a parser error occurs if you do not specify a font URI value or you do not specify any glyph information such as the Unicode string or the glyph indices.

To render any text with IXRGlyphs, you must also specify values for the fill and for the font-rendering em size, either in the source XAML or by calling IXRGlyphs::SetFill and IXRGlyphs::SetFontRenderingEmSize.

When you create a class instance, use an IXRGlyphsPtr smart pointer instead of a raw interface pointer. For more information, see XRPtr<Interface>.

You can also define a glyphs element in Microsoft Silverlight 3 XAML. For information about the differences between XAML in XAML for Windows Embedded and Silverlight 3, see Differences Between Microsoft Silverlight 3 and XAML for Windows Embedded. For more information about how to define a glyph element in the source XAML for your application, see the Glyphs Class on MSDN.

.NET Framework Equivalent

System.Windows.Documents.Glyphs

Requirements

See Also

Reference

Classes for UI Element Management