Using embedded fonts

To embed TrueType or OpenType fonts, you use the following syntax in your style sheet or <fx:Style> tag:

@font-face { 
    src: url("location"); 
    fontFamily: alias; 
    [fontStyle: normal | italic | oblique] ; 
    [fontWeight: normal | bold | heavy] ; 
    [embedAsCFF:true | false] ; 
    [advancedAntiAliasing: true | false]; 
}

The src property specifies the file path location of a font. In Flex 4, you cannot embed a font by its local name only.

The fontFamily property sets the alias for the font that you use to apply the font in style sheets. This property is required. If you embed a font with a family name that matches the family name of a system font, the Flex compiler gives you a warning. You can disable this warning by setting the show-shadows-system-font-warnings compiler option to false.

The fontStyle and fontWeight properties set the type face values for the font. These properties are optional, unless you are embedding a face that requires them. The default values are normal.

The embedAsCFF (Compact Font Format) property indicates whether to embed an FTE-enabled font for components. Flash Text Engine (FTE) is a library that provides text controls with a rich set of formatting options. For Flex 4, the default value is true. If you set the compatibility-version compiler option to 3.0, then the default value is false.

If you set the embedAsCFF property to true, then the embedded font will let you use the advanced formatting features of FTE such as bidirectional text, kerning, and ligatures. If you set the value of embedAsCFF to false, then the embedded font will not support FTE, and will work only with the MX text components. The default value is true. For information on using FTE-based classes for text rendering in your MX text controls, see Embedding fonts with MX components.

The advancedAntiAliasing property determines whether to include the advanced anti-aliasing information when embedding the font. This property is optional and only used for legacy fonts. This property is ignored if you embed a font with the embedAsCFF property set to true. You cannot use this option when embedding fonts from a SWF file because this option requires access to the original, raw font file to pre-calculate anti-aliasing information at compile time. For more information on using advanced anti-aliasing, see Using advanced anti-aliasing with non-CFF based fonts.

The following example embeds the MyriadWebPro.ttf font file:

@font-face { 
    src: url("../assets/MyriadWebPro.ttf"); 
    fontFamily: myFontFamily; 
    embedAsCFF: true; 
}

After you embed a font with an @font-face declaration, you can use the value of the fontFamily property, or alias, in a selector’s property declarations. The following example uses myFontFamily, the value of the fontFamily property, as the font in the VGroup type selector:

<?xml version="1.0"?>
<!-- fonts/EmbeddedFontFace.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark">

    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout>

  <fx:Style>
     @namespace s "library://ns.adobe.com/flex/spark";

     @font-face {
        src:url("../assets/MyriadWebPro.ttf");
        fontFamily: myFontFamily;
        embedAsCFF: true;
     }
     
     s|VGroup {
        fontFamily: myFontFamily;
        fontSize: 15;
     }     
  </fx:Style>

  <s:Panel title="Embedded Font Applied With Type Selector">
     <s:VGroup>
        <!-- This MX button tries to use a system font. -->
        <mx:Button label="Click Me"/>

        <!-- This Spark button uses the font of the VGroup container. -->
        <s:Button label="Click Me"/>
        <s:Label text="This is a Label control."/> 
        <s:RichText width="250">
            <s:text>
                The text in this RichText control uses the 
                font set on the VGroup.
            </s:text>
        </s:RichText>
     </s:VGroup>
  </s:Panel>

  <!-- This button uses the default font because it is not in the VGroup. -->
  <s:Button label="Click Me"/>
    
</s:Application>
The executing SWF file for the previous example is shown below:

When you run this example, you might notice that the MX Button (in the mx namespace) control’s label disappears. This is because the default style of an MX Button control’s label uses a bold typeface. However, the embedded font’s typeface (Myriad Web Pro) does not contain a definition for the bold typeface.

The Spark Button (in the s namespace) control’s label renders with the embedded font because it does not require a bold faced font.

You can also apply the embedded font inline by specifying the alias as the value of the control’s fontFamily property, as the following example shows:

<?xml version="1.0"?>
<!-- fonts/EmbeddedFontFaceInline.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark">

    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout>

  <fx:Style>
     @font-face {
        src:url("../assets/MyriadWebPro.ttf");
        fontFamily: myFontFamily;
        embedAsCFF: true;
     }
  </fx:Style>

  <s:Panel title="Embedded Font Applied Inline">
     <s:VGroup fontFamily="myFontFamily">
        <s:Button label="Click Me"/>
        <s:Label text="This is a Label."/> 
        <s:RichText width="200" fontFamily="myFontFamily">
            <s:text>The text in the RichText control is Myriad Web Pro.</s:text>
        </s:RichText>
     </s:VGroup>
  </s:Panel>
</s:Application>
The executing SWF file for the previous example is shown below:

Flex 3 components in the Halo theme use non-CFF fonts. The text in these components is rendered with the flash.text.TextField API (instead of the new Flash Text Engine (FTE).

When you embed non-CFF fonts (with the embedAsCFF property set to false), you can use advanced anti-aliasing to provide those fonts with additional information about the font. Non-CFF embedded fonts that use the advanced anti-aliasing information are typically clearer and appear sharper at smaller font sizes. CFF fonts have this information by default.

By default, non-CFF fonts that you embed in applications use the advanced anti-aliasing information. This default is set by the fonts.advanced-anti-aliasing compiler option in the flex-config.xml file (the default value is true). You can override this default value by setting the value in your style sheets or changing it in the configuration file. To disable advanced anti-aliasing in style sheets, you set the advancedAntiAliasing style property to false in your @font-face rule, as the following example shows:

@font-face { 
    src:url("../assets/MyriadWebPro.ttf"); 
    fontFamily: myFontFamily; 
    advancedAntiAliasing: false; 
    embedAsCFF: false; 
}

Using advanced anti-aliasing can degrade the performance of your compiler. This is not a run-time concern, but can be noticeable if you compile your applications frequently or use the web-tier compiler. Using advanced anti-aliasing can also cause a slight delay when you load SWF files. You notice this delay especially if you are using several different character sets, so be aware of the number of fonts that you use. The presence of advanced anti-aliasing information may also cause an increase in the memory usage in Flash Player and Adobe® AIR™. Using four or five fonts, for example, can increase memory usage by approximately 4 MB.

When you embed non-CFF fonts that use advanced anti-aliasing in your applications, the fonts function exactly as other embedded fonts. They are anti-aliased, you can rotate them, and you can make them partially or wholly transparent.

Font definitions that use advanced anti-aliasing support several additional styles properties: fontAntiAliasType, fontGridFitType, fontSharpness, and fontThickness. These properties are all inheriting styles, but they are applied on the component being styled. They are not relevant to the actual font embedding process (and thus must not be specified in the @font-face rule).

Because the advanced anti-aliasing-related style properties are CSS styles, you can use them in the same way that you use standard style properties, such as fontFamily and fontSize. For example, a text-based component could use subpixel-fitted advanced anti-aliasing of New Century 14 at sharpness 50 and thickness -35, while all Button controls could use pixel-fitted advanced anti-aliasing of Tahoma 10 at sharpness 0 and thickness 0. These styles apply to all the text in a TextField control; you cannot apply them to some characters and not others.

The default values for the advanced anti-aliasing styles properties are defined in the defaults.css file. If you replace this file or use another style sheet that overrides these properties, Flash Player and AIR use the standard font renderer to render the fonts that use advanced anti-aliasing. If you embed fonts that use advanced anti-aliasing, you must set the fontAntiAliasType property to advanced, or you lose the benefits of the advanced anti-aliasing information.

The following table describes these properties:

To use functionality similar to advanced anti-aliasing with CFF based fonts, you use the functionality of FTE that is built into Spark’s text-based controls. For more information, see Formatting text.

You can use the SystemManager class’s isFontFaceEmbedded() method to determine whether the font is embedded or whether it has been registered globally with the register() method of the Font class. The isFontFaceEmbedded() method takes a single argument—the object that describes the font’s TextFormat—and returns a Boolean value that indicates whether the font family you specify is embedded, as the following example shows:

<?xml version="1.0"?>
<!-- fonts/DetectingEmbeddedFonts.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark"
     creationComplete="determineIfFontFaceIsEmbedded()">
     
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout>
     
  <fx:Style>
     @font-face {
        src: url(../assets/MyriadWebPro.ttf);
        fontFamily: myPlainFont;
        embedAsCFF: true;
     }
     
     .myStyle1 {
        fontFamily: myPlainFont; 
        fontSize:12pt
     }
  </fx:Style>
  
  <fx:Script><![CDATA[
     import mx.managers.SystemManager;
     import mx.core.FlexGlobals;
     import flash.text.TextFormat;
     
    [Bindable]
     private var b1:Boolean;
    [Bindable]
     private var b2:Boolean;
     
     public function determineIfFontFaceIsEmbedded():void {
        var tf1:TextFormat = new TextFormat();
        tf1.font = "myPlainFont";
        
        var tf2:TextFormat = new TextFormat();
        tf2.font = "Arial";
        
        b1 = FlexGlobals.topLevelApplication.systemManager.
           isFontFaceEmbedded(tf1);
        b2 = FlexGlobals.topLevelApplication.systemManager.
           isFontFaceEmbedded(tf2);
     }
  ]]></fx:Script>

  <mx:Form>
     <mx:FormItem label="isFontFaceEmbedded (myPlainFont):">
        <mx:Label id="l1" text=" {b1}"/>
     </mx:FormItem>         
     <mx:FormItem label="isFontFaceEmbedded (Arial):">
        <mx:Label id="l2" text="{b2}"/>
     </mx:FormItem>         
  </mx:Form>    
</s:Application>
The executing SWF file for the previous example is shown below:

In this example, the font identified by the myPlainFont family name is embedded, but the Arial font is not.

You can use the Font class’s enumerateFonts() method to output information about device or embedded fonts. The following example lists embedded fonts:

<?xml version="1.0"?>
<!-- fonts/EnumerateFonts.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark"
    creationComplete="listFonts()">
    
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout>

  <fx:Style>
     @font-face {
        src:url("../assets/MyriadWebPro.ttf");
        fontFamily: myFont;
        embedAsCFF: true;
     }

     @font-face {
        src:url("../assets/MyriadWebPro-Bold.ttf");
        fontFamily: myFont;
        fontWeight: bold;
        embedAsCFF: true;
     }

     @font-face {
        src:url("../assets/MyriadWebPro-Italic.ttf");
        fontFamily: myFont;
        fontStyle: italic;
        embedAsCFF: true;
     }
     
     .myPlainStyle {
        fontSize: 20;
        fontFamily: myFont;
     }
     
     .myBoldStyle {
        fontSize: 20;
        fontFamily: myFont;
        fontWeight: bold;
     }

     .myItalicStyle {
        fontSize: 20;
        fontFamily: myFont;
        fontStyle: italic;
     }
  </fx:Style>

  <fx:Script><![CDATA[
     private function listFonts():void {
        var fontArray:Array = Font.enumerateFonts(true);
        ta1.text += "Fonts: \n";
        for(var i:int = 0; i < fontArray.length; i++) {
            var thisFont:Font = fontArray[i];
            ta1.text += "FONT " + i + ":: name: " + thisFont.fontName + "; typeface: " + 
                thisFont.fontStyle + "; type: " + thisFont.fontType;
            if (thisFont.fontType == "embeddedCFF"||thisFont.fontType == "embedded") {
                ta1.text += "*";              
            }            
            ta1.text +=  "\n";
            
        }
        
     }
  ]]></fx:Script>

  <s:VGroup> 
     <s:RichText text="Plain Label" styleName="myPlainStyle"/> 
     <s:RichText text="Bold Label" styleName="myBoldStyle"/> 
     <s:RichText text="Italic Label" styleName="myItalicStyle"/> 
     <s:TextArea id="ta1" height="200" width="400"/>
     <s:RichText text="* Embedded" styleName="myItalicStyle"/> 
  </s:VGroup>
</s:Application>
The executing SWF file for the previous example is shown below:

The following list shows the first few lines of sample output. This list will vary depending on the client’s system.

FONT 0:: name: myFont; typeface: regular; type: embeddedCFF* 
FONT 1:: name: myFont; typeface: bold; type: embeddedCFF* 
FONT 2:: name: myFont; typeface: italic; type: embeddedCFF* 
FONT 3:: name: Marlett; typeface: regular; type: device 
FONT 4:: name: Arial; typeface: regular; type: device 
FONT 5:: name: Arial CE; typeface: regular; type: device

The enumerateFonts() method takes a single Boolean argument: enumerateDeviceFonts. The default value of the enumerateDeviceFonts property is false, which means it returns an Array of embedded fonts by default.

If you set the enumerateDeviceFonts argument to true, the enumerateFonts() method returns an array of available device fonts on the client system, but only if the client’s mms.cfg file sets the DisableDeviceFontEnumeration property to 0, the default value. If you set the DisableDeviceFontEnumeration property to 1, Flash Player cannot list device fonts on a client computer unless you explicitly configure the client to allow it. For more information about configuring the client with the mms.cfg file, see the Flash Player documentation.

The fontswf utility is a simple command line tool that converts a single font face from a font file into a SWF file. This SWF file can be used as the source of an embedded font in your applications. Supported font file types are *.ttf, *.otf, *.ttc, and *.dfont.

The fontswf utility is for users of the Mozilla Public License version of the Flex SDK. This version includes only open-source technology. Because the font managers are not open-source, this utility can be used in their place so that you can embed fonts in your applications.

fontswf [options] font_input_file

c:\flex\bin> fontswf -4 -u U+0020-007F -bold -o c:/temp/myboldfont.ttf c:/assets/fonts/myboldfont.ttf