Embed Fonts in a XAML for Windows Embedded Application (Compact 2013)

  • Article

3/26/2014

Font embedding ensures that an application will display text exactly the way you designed it. For example, if an application that uses the Courier New font runs in an OS design that does not include the font, a default font will be used unless the Courier New font is embedded in the application itself.

Font embedding is especially useful if your application is localized and the OS design must support AC3 font compression. AC3 font compression is not supported by XAML for Windows Embedded. To make the correct font appear in your application, you can embed the uncompressed versions of font files in your application and use those. For more information, see Font Compression below.

To embed fonts in an application for XAML for Windows Embedded:

  • Step 1: Determine Whether the OS Design Already Includes the Uncompressed Font
  • Step 2: Select a Supported Font
  • Step 3: Embed the Font in the Application
  • Step 4: Format Text in an XAML File Using the Embedded Font

Note

Microsoft Silverlight desktop and web applications can minimize application size by embedding subsets of fonts in the application instead of embedding a full font set. XAML for Windows Embedded does not provide subsetting functionality.

Prerequisites

The procedures in this topic require one of the following:

  • An OS design project that includes the XAML for Windows Embedded catalog item (SYSGEN_XAML_RUNTIME).
  • An installed SDK that was generated from an OS design project that includes the XAML for Windows Embedded catalog item.

You can perform these procedures after you have created a XAML for Windows Embedded subproject for the OS design. For more information, see Getting Started with XAML for Windows Embedded.

Step 1: Determine Whether the OS Design Already Includes the Uncompressed Font

Determine whether the OS design already includes the font that you want to use. If it does, you do not have to embed the font in your application unless the OS must support AC3 font compression. For more information, see Font Compression.

To determine whether a font is included in your OS design

  • If you have Platform Builder installed, open the OS design project in Visual Studio. On the View menu, click Other Windows, and then click Catalog Items View. In Catalog Items View, in the Filter drop-down box, select User-selected Catalog Items and Dependencies, type font in the search window, and then press Enter to locate font-related items.

    If the font that you want to use is selected, it is included in the OS design.

  • If you have installed the SDK for the OS design, open the BuildSDK_name.xml file that was included with the SDK. All of the Sysgen variables that are included in the OS design are listed under the node <PropertyBag NAME="SYSGENS">. Search for those that begin with SYSGEN_FONTS_*.

    If the font that you want is listed, it is included in the OS design.

Tip

For more information about Sysgen variable names for fonts, see Fonts Catalog Items and Sysgen Variables and see the Sysgen topics for the individual languages listed under International.

To determine whether AC3 compression is supported

  • If you have Platform Builder installed, click Catalog Items View, type Monotype Imaging AC3 Font Compression in the search window, and then press Enter to locate the catalog item.

    If you find the item and the box next to it is selected, AC3 compression is enabled.

  • If you have installed the SDK for the OS design, open the BuildSDK_name.xml file that was included with the SDK. Under the <PropertyBag NAME="SYSGENS"> node, search for SYSGEN_AC3_FONT.

    If the item is listed, AC3 compression is enabled.

If the font that you want to use is included in the OS design, but AC3 compression is enabled, you will have to embed the uncompressed version of the font file (.ttf, .ttc) in the XAML for Windows Embedded application, or ask the OS designer if AC3 compression can be disabled. For more information, see Font Compression.

If the font is included in the OS design, and AC3 compression is disabled, you do not have to embed the font in the application, and you do not have to modify the FontFamily attributes in the XAML in the application.

If you have determined that you have to embed a font in the application, continue with the following sections.

Step 2: Select a Supported Font

You can embed fonts in XAML for Windows Embedded applications if they meet the following criteria:

  • The font is a TrueType font that is contained in a .ttf or .ttc file.
  • The font is supported by Windows Embedded Compact. For a list of supported fonts, see Fonts Catalog Items and Sysgen Variables and see the Sysgen topics for the individual languages listed under International.
  • The font is licensed for embedding. This includes most fonts included with Microsoft products. With Windows 7 you can determine whether a font can be embedded in your XAML for Windows Embedded application by browsing the font folder (usually C:\Windows\Fonts) in Windows Explorer. When you select a font in Windows Explorer, the font details are displayed in the lower part of the window. Fonts that can be embedded will have the text "Font embeddability: Editable" in the details.

Important

If you choose to embed non-Microsoft fonts in your application, make sure that you have the required license rights for those fonts. For commercial fonts, see Microsoft Typography, which includes information that can help you locate a particular font vendor or find a font vendor for custom work. For fonts that come with individual Microsoft products such as Blend for Visual Studio, check the Microsoft Software License Terms file for full license terms.

Keep the file size in mind when you make the decision to embed fonts or font collections in XAML for Windows Embedded. Storage on embedded devices is often limited, and fonts embedded in XAML for Windows Embedded applications are embedded in their entirety. Partial embedding of fonts is supported only in the desktop versions of Silverlight 3.

Step 3: Embed the Font in the Application

A font is embedded into the XAML for Windows Embedded application as an application resource. You instruct the compiler to embed the resource by modifying your application resource file. Use the following procedures for each individual font file that you want to embed in your application.

To embed the font in your application

  1. Copy the font file from your C:\Windows\Fonts folder to your XAML for Windows Embedded subproject folder. This ensures that the font is always available to your application, even if the location of the application source changes.

  2. Open the application resource file, Project_Name.rc, in Notepad or other text editor.

    Tip

    You cannot make the necessary changes in Visual Studio.

  3. Add the font as a resource by typing the following text at the end of the file on a line by itself, as shown in the following example.

    font_file_name XAML_RESOURCE DISCARDABLE font_file_name

    For example, if you are using the Courier New Regular font, add the following text.

     cour.ttf XAML_RESOURCE DISCARDABLE cour.ttf

    The first instance of the font file name is the identifier that you will use to reference the resource in the source code, and the second instance is the name of the file to embed.

    Tip

    Add a new line for each font you want to include in your application. Make sure to consider the size of the font files and how much limited space your device will have.

  4. Save the Project_Name.rc file and close it.

  5. In Visual Studio, a popup appears and asks you if you want to reload the resource file. Click Yes.

    Now when you view the resource file in Resource View, you will see a node for "XAML_RESOURCE" that contains a child element for the font file.

OS design subprojects provide a verbose description of the progress at each stage of the build process, so it is easy to miss warnings that could result in your application not building correctly. To confirm that the font was embedded correctly, open your application executable using the resource editor and verify that the font exists.

To confirm that the font is embedded in your application executable

  1. In Visual Studio, in Solution Explorer, locate and right-click the XAML for Windows Embedded subproject folder, and then click Build. Confirm that the project builds successfully.

  2. In Visual Studio, on the File menu, click Open, and then click File.

  3. When the Open File dialog box appears, select your newly built executable. For example, your executable might be in a path similar to the following.

    C:\WINCE800\OSDesigns\OSDesign_Name\OSDesign_Name\Subproject_Name\obj\Board_Name\retail\Subproject_Name.exe

  4. Click Open.

  5. In the document window that appears, expand the XAML_RESOURCE tree node. If your resource was embedded correctly, the node will have a child element for the font file.

  6. Close the document window for the executable file. If you do not, you will not be able to build your subproject.

Step 4: Format Text in an XAML File Using the Embedded Font

Referencing a font from a resource file requires special syntax. Use the following procedure for each XAML element that you want to format using an embedded font.

To reference your embedded font in the XAML file

  1. In Visual Studio, in Solution Explorer, locate your XAML for Windows Embedded subproject folder and open the MainPage.xaml document located under the Resource Files node.

  2. In the XAML view, locate an element that displays text, such as a Button or TextBlock element, as shown in the following example.

    <TextBlock Text="Hello World" FontFamily="Courier New"/>

    If your subproject was converted from an Blend project that uses embedded fonts, it might resemble the following example.

    <TextBlock Text="Hello World" FontFamily="Fonts/Fonts.zip#Courier New"/>

  3. Change the FontFamily attribute so that the resource ID and a pound symbol come before the font name, as shown in the following example.

    <TextBlock Text="Hello World" FontFamily="COUR.TTF#Courier New"/>

    There are different font files for each font weight (for example, bold and demibold) and font style (for example, italic). Remember to add the font weight and font style attributes when you use those corresponding font files. For example, if you created TextBlock elements that used all four Courier New font files, your XAML might resemble the following example.

    <TextBlock Text="Hello World" FontFamily="COUR.TTF#Courier New" />
<TextBlock Text="Hello World" FontFamily="COURBD.TTF#Courier New" FontWeight="Bold" />
<TextBlock Text="Hello World" FontFamily="COURBI.TTF#Courier New" FontWeight="Bold" FontStyle="Italic" />
<TextBlock Text="Hello World" FontFamily="COURI.TTF#Courier New" FontStyle="Italic" />

Important

In XAML for Windows Embedded applications, the FontFamily attribute is a late-bound property. Therefore, syntax errors in the value string will not cause the build process to fail. You will not notice a problem until you test the application on your device. If there is a syntax error, your application will not run. For example, the FontFamily="Fonts/Fonts.zip#Segoe Script" syntax or the inclusion of the XAML attribute FontWeight="Bold" will prevent your application from running on your device. For more information about how to verify that the font displays correctly on your device, see Create Your First Application.

Important

If you use Blend to modify the project after following this procedure, remember not to change your new font settings. The new font settings will not break your application in Blend, but default fonts will be used.

Font Compression

Font compression is used to reduce the ROM and RAM effect of large font files, such as those for East Asian fonts. AC3 fonts are TrueType fonts in a compressed format.

XAML for Windows Embedded does not support AC3 font compression and .ac3 files. If you include .ac3 font files in your OS, you must use one of the following methods when you use XAML for Windows Embedded:

  • Clear the Sysgen variable for Monotype Imaging AC3 Font Compression (SYSGEN_AC3_FONT) for each language used by your XAML for Windows Embedded application. This will disable font compression for all applications that run in your OS design.
  • Embed and use the non-compressed versions of font files (.ttf and .ttc) in your XAML for Windows Embedded application. If you use this option, your OS image will include both compressed and non-compressed versions of the same fonts. If you want to reduce the size of your OS image, disable AC3 font compression instead.

Otherwise, characters will display incorrectly in the user interface of your application because the system will attempt to use the .ac3 font files before looking for .ttf and .ttc font files.

See Also

Concepts

XAML for Windows Embedded Application Development