IXRGlyphs (Windows Embedded CE 6.0)

1/6/2010

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

Syntax

class IXRGlyphs : public IXRFrameworkElement

Methods

Remarks

IXRGlyphs is a low-level mechanism for rendering specific text and applying special decorations to it. This text has already been preformatted by a text-layout and writing-system engine. For all other scenarios, IXRTextBlock should be used.

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.

Usually, glyphs should be drawn on-screen by using both the set of glyph indices and the Unicode string. The set of glyph indices is used by rendering software to display the glyphs on-screen, whereas the underlying Unicode string provides the original text for use by applications that support text search features or that otherwise must internally read and process characters in the string.

One way to use IXRGlyphs is with the XML Paper Specification (XPS) document format. You can borrow the XPS formatted output of a document-producing application such as Microsoft Office Word 2007. The XPS format produces packages that define the document. One part of this packaging format is a XAML page that declares a FixedPage element by using the XPS schema (this schema has a namespace https://schemas.microsoft.com/xps/2005/06). Glyphs is also an element of that schema. You can open up the package, find your FixedPage parts, extract the Glyphs from them, and paste the Glyphs into the source XAML, or into the Set* methods in this class, such as the IXRGlyphs::SetIndices method.

If an IXRGlyphs object should 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 glyphs objects, while providing its own support for search, copy/paste, and accessibility.

When the mapping of Unicode characters to glyph indices and to glyph positions is simple, you can supply a value to SetUnicodeString, but do not have to supply a value to SetIndices. This 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 specified by IXRGlyphs::GetFontUri. These restrictions severely limit text that is displayed in this manner. 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, 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, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayalam, Sinhala)
  • Tibetan
  • Limbu
  • Ethiopic
  • Mongollian

In addition to the glyph information, you must always provide a font 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 will occur if you do not specify a font URI value or do not specify any glyph information such as the Unicode string or the glyph indices.

To render any text with IXRGlyphs, you should 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.

You can also define a glyphs element in Microsoft Silverlight 2 XAML. For information about the differences between XAML in Silverlight for Windows Embedded and Silverlight 2, see Differences Between Silverlight for the Web and Silverlight for Windows Embedded. For more information about how to define this element in the source XAML for your application, see this Microsoft Web site.

Inheritance Hierarchy

IXRDependencyObject

    IXRUIElement

        IXRFrameworkElement

            IXRGlyphs

.NET Framework Equivalent

System.Windows.Documents.Glyphs

Requirements

See Also

Reference

Classes for UI Element Management