# Adding Fonts to the Java Runtime

This document explains how to add Asian and other language fonts to the Java Runtime JDK 1.1. More specifically, this document covers the JDK 1.1 special feature for adding these fonts to the Java Runtime. It is very likely that this feature will change in future JDK releases.

At this time, this document describes how to install Japanese, Korean, Chinese, and Traditional Chinese fonts to your system.

If the core Java Runtime includes support only for Latin-1 fonts, then the Runtime requires only one `font.properties` file. All other `font.properties` files can be in the optional I18n package.

The JDK 1.1 release for Win32 platforms supports TrueType fonts. JDK 1.1 for Solaris supports outline fonts that can be handled by an X11 server, such as F3, Type1, and TrueType.

## Using the font.properties File

You must work with the `font.properties` file to add fonts to the Java Runtime. The `font.properties` file is platform- specific. It indicates the fonts that a particular platform uses for its Java virtual fonts. Fonts are grouped by types or classes. Currently, the Java Runtime supports the following classes of fonts:

- Serif
- Sans-serif
- Monospaced
- Dialog
- DialogInput

There are several `font.properties` files that come bundled with the JDK 1.1. You can find these files in the directory `../lib` that is beneath the directory where Java is installed. These files contain standard font environment information. The explanations that follow assume that the readers of this document are working in an English environment. In an English environment, you use the `font.properties` file with no suffix on its file name, as follows:

>     font.properties

However, if your environment is Japanese, Korean, Chinese, or Traditional Chinese, then you must use the `font.properties` file that corresponds to your particular environment. These files can be identified by the country or locale suffix that is appended to the file name, as follows:

>     font.properties.<locale>

where `locale` is one of:

>     ja

>     ko

>     zh

>     zh_TW

>     ...

Select the file with the suffix for the particular font that you are interested in. Thus, for Traditional Chinese, you would access the file `font.properties.zh_TW`.

## Adding Asian Fonts to the Java Runtime

There are two steps you must take to use Asian fonts, such as the Japanese font, on an English environment platform.

### Step 1: Install the Font

First, you must install the Japanese, Korean, Chinese, or Traditional Chinese font to your system. For Windows platform users, Microsoft delivers these Asian fonts free with the NT4.0 installation CD. Or, you can download these fonts from the Microsoft World Wide Web home page. Solaris users must contact SunSoft to request the Asian outline fonts for Solaris environments.

### Step 2: Copy the Font

Once you have installed the fonts on your system, copy the font description that you are interested in to `font.properties`. The easiest way to add one Asian font is to rename the font.properties.<locale> file to be the new `font.properties` file. The locale symbol represents the font name that you are interested in. No editing is required when you replace `font.properties` with font.properties.<locale> because font.properties.<locale> is a superset of `font.properties`. These are the locale symbols that specify the different font properties files:

### Locale Symbols for Fonts

Font Name | `font.properties` Symbol
Japanese | `ja`
Korean | `ko`
Chinese | `zh`
Traditional Chinese | `zh_TW`

Thus, to use the the Korean font, you copy or rename `font.properties.ko` to `font.properties`.

## Using Multiple Fonts in the Runtime

It is possible to use more than one Asian font in your runtime. To do this, you must edit the `font.properties` file. This section describes the edits you need to make to the file to use multiple Asian fonts. The `font.properties` file defines certain information about the fonts for your platform. This includes aliases, such as:

>     alias.timesroman=serif

>     alias.helvetica=sansserif

It also includes descriptions for the fonts. The descriptions differ between the Win32 and Solaris platforms. Our examples use serif fonts to illustrate how fonts are specified and converted, if necessary. However, the same entries apply to other types of fonts. In general, there are entries in the font properties file that specify the fonts you want to use. These entries have the following format:

       <virtual font name>.<index number> = <platform font name>, attributes

The virtual font name is the name of the font as recognized by the Java Runtime. The platform font name is the actual name of the font on your platform. For example, Dialog and Serif are Java font names, while Times and Helvetica are the native font names on a Win32 or Solaris platform. The index number specifies the order of searching for matching font glyphs, with zero the highest priority.

### Specifying Fonts on Win32 Platform

There are three default serif fonts available on an English language Win32 platform. These fonts are:

- Times New Roman
- WingDings
- Symbol

In addition, the descriptions for these serif fonts in the `font.properties` file are as follows:

>     serif.0=Times New Roman,ANSI_CHARSET

>     serif.1=WingDings,SYMBOL_CHARSET,NEED_CONVERTED

>     serif.2=Symbol,SYMBOL_CHARSET,NEED_CONVERTED

These three lines together indicate the indexes for the three serif fonts that are available on this platform. Each line indicates one serif font, followed by up to three arguments for that font.

The numbers (0, 1, and 2) that appear after the word `serif`, such as `serif.0`, indicate the order in which the font glyphs are searched for a corresponding match with the Unicode, or Java string encoding, codepoint. Thus, if `serif.0` and `serif.1` both have the glyph that corresponds to the same Unicode codepoint, then the glyph for `serif.0` will be used.

The first argument is the face name of the Win32 native font. Each line names a particular font. For example, the line for `serif.0` names the font Times New Roman, while the line for `serif.2` names the font Symbol.

The second argument takes the form `*_CHARSET`. In our example, it is either `ANSI_CHARSET` or `SYMBOL_CHARSET`. This argument indicates the charset entry of the corresponding font in Win32. (See the Win32 API document for more details.)

The third argument, if present, is `NEED_CONVERTED`. This argument indicates that the corresponding platform font cannot be accessed with Unicode. When this argument is present, the Java Runtime needs to convert the Unicode string to this font index before attempting to use the glyph for the font. Fonts that have this `NEED_CONVERTED` argument must have a corresponding fontcharset entry, which indicates the charset converter to use to convert the Unicode string.

In our example, both serif.1 and serif.2 have the `NEED_CONVERTED` argument. Both have fontcharset entries in the font.properties file, as follows:

>     fontcharset.serif.1=sun.awt.windows.CharToByteWingDings

>     fontcharset.serif.2=sun.awt.CharToByteSymbol

The fontcharset entry for `serif.1` indicates that, to draw the WingDings glyph, the Unicode string should be converted using the `sun.awt.windows.CharToByteWingDings` converter. (Recall that the font.properties file has already established the font for `serif.1` as WingDings.)

The specification for the charset converter is described later in the section The Charset Converter.

### Win32 Font Files

The current Win32 JDK build provides the following font properties files:

>     ./lib/font.properties

>     ./lib/font.properties.ja

>     ./lib/font.properties.ko

>     ./lib/font.properties.zh

>     ./lib/font.properties.zh_TW

If you need a different font from what is provided, then you must create your own font properties file.

### Specifying Fonts on Solaris Platform

The Solaris `font.properties` file uses a different format for specifying fonts than the Win32 version. The Solaris version uses fixed-width, rather than proportional, platform fonts. For example, the serif font on an English Solaris platform consists of the following fixed-width fonts:

    serif.plain.0=-linotype-times-medium-r-normal--*-%d-*-*-p-*-iso8859-1

    serif.1=-urw-itc zapfdingbats-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific

    serif.2=--symbol-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific

    serif.italic.0=-linotype-times-medium-i-normal--*-%d-*-*-p-*-iso8859-1

    serif.bold.0=-linotype-times-bold-r-normal--*-%d-*-*-p-*-iso8859-1

    serif.bolditalic.0=-linotype-times-bold-i-normal--*-%d-*-*-p-*-iso8859-1

These lines from the Solaris `font.properties` file indicate the indexes for serif fonts with different styles. For example, the font whose face name is serif and whose style is plain consists of `serif.plain.0`, `serif.1`, and `serif.2`. In addition, these lines indicate that the serif font with the style italic consists of `serif.italic.0`, `serif.1`, and `serif.2`.

Currently, the index of Solaris (X11) font is not a Unicode index. Because it is not Unicode, the font always needs to be converted. Each entry must have a corresponding fontcharset entry to indicate how it should be converted, as follows:

>     fontcharset.serif.0=sun.io.CharToByteISO8859_1

>     fontcharset.serif.1=sun.awt.motif.CharToByteX11Dingbats

>     fontcharset.serif.2=sun.awt.CharToByteSymbol

For example, the line:

>     fontcharset.serif.0=sun.io.CharToByteISO8859_1

indicates that all `serif.0` fonts, regardless of whether the type is plain (`serif.plain.0`), bold (`serif.bold.0`), italics (`serif.italic.0`), or bold and italics (`serif.bolditalic.0`), will be converted using the `sun.io.CharToByteISO8859_1` converter.

### Solaris Font Files

The current Solaris JDK build provides the following font properties files:

>     ./lib/font.properties

>     ./lib/font.properties.ja

>     ./lib/font.properties.ko

>     ./lib/font.properties.zh

>     ./lib/font.properties.zh_TW

>     ./lib/font.properties.cs

>     ./lib/font.properties.el

>     ./lib/font.properties.hu

>     ./lib/font.properties.lt

>     ./lib/font.properties.lv

>     ./lib/font.properties.pl

>     ./lib/font.properties.ru

>     ./lib/font.properties.tr

>     ./lib/psfont.properties.ja

If you need a different font from what is provided, then you must create your own font properties file.

## The Charset Converter

The `charset` converter converts Unicode, or Java string encoding, to the index of the font. For font drawing, the JDK 1.1 Runtime uses the `charset` converter that is the subclass of `sun.io.CharToByteConverter`.

To add your own font to your JDK 1.1 Runtime, you need to create a `charset` converter and specify it in the `font.properties file`.

The following example illustrates how to add your own platform font to the Java serif font. In this example, your font contains 256 glyphs, which are indexed 0 - 0xff. Your font's glyphs correspond to Unicode 0xe000 - 0xe0ff. This example is divided into two steps. First, you create your `fontcharset` converter class. Second, you specify your font name and converter class name in the `font.properties file` file.

### Step 1. Create fontcharset Converter

This is the Java code for creating the `fontcharset` converter.

>     package mypkg.converter;

>     import sun.io.CharToByteISO8859_1;
>     import sun.io.CharToByteConverter;
>     import sun.io.ConversionBufferFullException;

>     public class CharToByteMyFont extends sun.io.CharToByteISO8859_1 {

>        /*
>         * This method indicates the range this font covers.
>         */
>        public boolean canConvert(char ch) {
>           if (ch >= 0xe000 && ch <= 0xe0ff) {
>              return true;
>           }
>           return false;
>        }

>        /*
>         * This method converts the unicode to this font index.
>         */
>        public int convert(char[] input, int inStart, int inEnd,
>                           byte[] output, int outStart, int outEnd)
>                           throws ConversionBufferFullException {
>           int outIndex = outStart;
>           for (int i = inStart; i < inEnd; i++) {
>              char ch = input[i];
>              if (ch >= 0xe000 && ch <= 0xe0ff) {
>                 if (outIndex >= outEnd)
>                 throw new ConversionBufferFullException();
>                 output[outIndex++] = (byte)(ch - 0xe000);
>              }
>           }
>           return outIndex - outStart;
>        }

>        /*
>         * This method indicates the charset name for this font.
>         */
>        public String toString() {
>           return "MyFont";
>        }
>     }

### Step 2. Add Font and Converter to Properties File

You must first set the font name in the `font.properties` file. Do this by adding an index entry for the font. For example, for a serif font, add a line that designates the serif font followed by the next sequential index number in the file. The Java Runtime requires that the index numbers for any one font be continuous.

Thus, to add a serif font to our previous example font.properties file, you would insert the following line:

>     serif.3=<your own font name>

The index number must be the next highest index number in the properties file. In our example file, we have already used `serif.0`, `serif.1`, and `serif.2`. Therefore, the new serif font must be `serif.3`. Had we used a number that was discontinuous, such as `serif.5`, the Java Runtime would not use that entry.

Next, you must define the converter for this font. This requires a `fontcharset` entry for the new font, in this case, `serif.3`. The following line is the `fontcharset` entry that uses the converter created in the Java code example:

>     fontcharset.serif.3=mypkg.converter.CharToByteMyfont

You must also ensure that your new converter is visible to the Java Runtime. To ensure that the Java Runtime can see your converter, your java application `classpath` must include the class path to the converter. In our example, we must be sure that the class `mypkg.converter.CharToByteMyfont` is visible to the Java Runtime. The simplest way to do this is to put this class under your `$JDK_HOME/classes/myown/package` directory.