The font.properties Files

The Java 2 platform defines five logical font names that every implementation must support: Serif, SansSerif, Monospaced, Dialog, and DialogInput. These logical font names are mapped to physical fonts in implementation dependent ways.

Sun's Java 2 Runtime Environments use font.properties files to map logical font names to physical fonts. There are several files to support different mappings depending on host operating system version and locale. The files are located in the lib directory within the J2RE installation. Users can edit or create their own font.properties files to adjust the mappings to their particular system setup. Note however that this is a modification of the J2RE, and Sun does not support modified J2REs.

Note that font.properties files are implementation dependent. Not all implementations of the Java 2 platform use them, and the format and content vary between different runtime environments as well as between releases. This document describes the format used by version 1.4.1 of Sun's Java 2 Runtime Environments.

1. Loading font.properties Files
2. Names Used in font.properties Files
3. Properties for All Platforms
4. Properties for Windows
5. Properties for Solaris and Linux

Loading font.properties Files

The font.properties files are properties files as specified by the java.io.InputStream)">Properties class and are loaded through that class. To find the appropriate file, the following information is used:

• JavaHome - the J2RE's directory, as given by the "java.home" system property.
• Language - the language of the initial default locale.
• Country - the country of the initial default locale.
• Encoding - the canonical name of the default encoding.
• OS - a string identifying an operating system variant:
  • For Windows, "NT", "98", "2000", "Me", "XP".
  • For Solaris, empty.
  • For Linux, "Redhat", "Turbo", "SuSE".
• Version - a string identifying the operating system version.

The runtime uses the first of the following files it finds:

    JavaHome/lib/font.properties.Language_Country_Encoding.OSVersion
    JavaHome/lib/font.properties.Language_Country_Encoding.OS
    JavaHome/lib/font.properties.Language_Country_Encoding.Version
    JavaHome/lib/font.properties.Language_Country_Encoding
    JavaHome/lib/font.properties.Language_Country.OSVersion
    JavaHome/lib/font.properties.Language_Country.OS
    JavaHome/lib/font.properties.Language_Country.Version
    JavaHome/lib/font.properties.Language_Country
    JavaHome/lib/font.properties.Language_Encoding.OSVersion
    JavaHome/lib/font.properties.Language_Encoding.OS
    JavaHome/lib/font.properties.Language_Encoding.Version
    JavaHome/lib/font.properties.Language_Encoding
    JavaHome/lib/font.properties.Language.OSVersion
    JavaHome/lib/font.properties.Language.OS
    JavaHome/lib/font.properties.Language.Version
    JavaHome/lib/font.properties.Language
    JavaHome/lib/font.properties.Encoding.OSVersion
    JavaHome/lib/font.properties.Encoding.OS
    JavaHome/lib/font.properties.Encoding.Version
    JavaHome/lib/font.properties.Encoding
    JavaHome/lib/font.properties.OSVersion
    JavaHome/lib/font.properties.OS
    JavaHome/lib/font.properties.Version
    JavaHome/lib/font.properties

Names Used in font.properties Files

Throughout the font.properties files, a number of different names are used:

• LogicalFontName - one of the five logical font names: serif, sansserif, monospaced, dialog, and dialoginput. In font.properties files, these names are always in lowercase.

  Some existing font.properties files also use other names as logical font names, such as helvetica or zapfdingbats. This usage is deprecated, and support for it will be removed in a future release.

• StyleName - one of the four standard font styles: plain, bold, italic, and bolditalic. Again, these names are always in lowercase.
• PlatformFontName - the name of a physical font in a format typically used on the platform:
  • On Windows, a font face name, such as "Courier New" or "\uad74\ub9bc".
  • On Solaris and Linux, an xlfd name, such as "-monotype-times new roman-regular-r---*-%d-*-*-p-*-iso8859-1". Note that "%d" is used for the font size - the actual font size is filled in at runtime.
• ComponentIndex - an integer identifying a component font entry within the set of entries for the same logical font and style. If there are n entries for a logical font and style, their indices must be 0 to n-1.
• WindowsCharsetName - one of the following Windows charset names: ANSI_CHARSET, DEFAULT_CHARSET, SYMBOL_CHARSET, SHIFTJIS_CHARSET, GB2312_CHARSET, HANGEUL_CHARSET, CHINESEBIG5_CHARSET, OEM_CHARSET, JOHAB_CHARSET, HEBREW_CHARSET, ARABIC_CHARSET, GREEK_CHARSET, TURKISH_CHARSET, VIETNAMESE_CHARSET, THAI_CHARSET, EASTEUROPE_CHARSET, RUSSIAN_CHARSET, MAC_CHARSET, BALTIC_CHARSET.

Properties for All Platforms

Component Font Mappings

Component font mapping properties describe which physical fonts to use to render characters with a given logical font in a given style. Typically there are several component font entries for each combination of logical font and style so as to cover a wide range of Unicode characters. The entries are identified by component indices. When rendering a character, the runtime checks the component fonts in the sequence defined by the component indices and uses the first one that can render the character and is not excluded.

The keys have the form:

ComponentFontMappingKey:
    LogicalFontName.StyleName.ComponentIndex
    LogicalFontName.ComponentIndex

If the StyleName is omitted, it's assumed to be plain. Within one logical font, the style name plain must either be present for all entries or omitted for all entries. The ComponentIndex identifies a component font entry within the set of entries for the same logical font and style. If there are n entries for a logical font and style, their indices must be 0 to n-1. Component indices must be used consistently between different styles for the same logical font, because some other properties only refer to the logical font name and the component index.

The form of the values depends on the platform. For Solaris and Linux, the values are platform font names. For Windows, the values have the form:

    PlatformFontName , WindowsCharsetName

The Windows charset name identifies the primary character set that this font is supposed to cover. The Java 2 runtime environment uses this information to select the component font to use in peered AWT text components, and Windows may use it to substitute a different font if the specified one cannot be found.

Component Font Character Encodings

Component font character encoding properties indicate which character encoding AWT should use when accessing the corresponding component fonts. These properties are only needed if the component fonts cannot be accessed using Unicode - newer TrueType fonts can usually be accessed using Unicode and don't need this property.

The keys have the form:

    fontcharset.LogicalFontName.ComponentIndex

The values are fully qualified class names of character converters. In this release, character converters are accessed using the old sun.io interfaces, so only the character encodings provided by the Java 2 Runtime Environment can be used. The class names for the publicly supported character encodings are of the form:

    sun.io.CharToByteCanonicalName

In a future release, character converters will be accessed through the new java.nio.charset API, which will enable the use of third-party character converters.

Exclusion Ranges

The exclusion range properties specify Unicode character ranges which should be excluded from being rendered with a given component font. This is used if a font with a large character repertoire needs to be placed early in the search sequence (for example, for performance reasons), but some characters that it supports should be drawn with a different font instead.

The keys have the form:

    exclusion.LogicalFontName.ComponentIndex

The values have the form:

ExclusionRangeValue:
    Range
    Range , ExclusionRangeValue
 
Range:
    Char - Char
 
Char:
    HexDigit HexDigit HexDigit HexDigit

A Char is a Unicode character represented as a hexadecimal value.

Font Name Aliases

Font name aliases are deprecated, and support for them will be removed in a future release.

The keys have the form:

    alias.LogicalFontName

The values have the form:

    LogicalFontName

Missing Glyph Character

Missing glyph character definitions are deprecated, and support for them will be removed in a future release.

The keys have the form:

    default.char

The values have the form:

    Char

Properties for Windows

Font File Names

Font file name properties provide the names of the files containing the physical fonts used in the font.properties file. Providing a complete set of file names reduces startup time, since the runtime system doesn't need to open all available font files to find the fonts.

The keys have the form:

    filename.PlatformFontName

Space characters in the platform font name must be replaced with underscore characters ("_").

The values are the simple file names of the files containing the fonts. The runtime environment will look for the file first in its own lib/fonts directory, then in the Windows fonts directory.

Text Input Character Set

Text input character set definitions are deprecated, and support for them will be removed in a future release.

The keys have the form:

    textinputcharset

The values have the form:

    WindowsCharsetName

Properties for Solaris and Linux

XFontSet Information

X font set definitions are deprecated, and support for them will be removed in a future release.

The keys have the forms:

    fontset.LogicalFontName.StyleName
    fontset.default

The values have the form:

FontSetValue:
    PlatformFontName
    PlatformFontName , FontSetValue