<html>

<head>

<title>Editing the font.properites Files</title>

</head>

<body bgcolor="#FFFFFF">
<center>
<h1>Editing the font.properties Files</h1>
</center>
<ul>
   <li><a href="#naming">Naming of the font.properties Files</a>
   <li><a href="#using">Using the font.properties File</a>
   <li><a href="#adding">Adding Locale-Specific Fonts to the Java Runtime</a>
   <ul>
       <li><a href="#adding1">Step 1: Install the Font</a>
       <li><a href="#adding2">Step 2: Copy the Font</a>
       <li><a href="#locale">Locale Symbols for Fonts</a>
   </ul>
   <li><a href="#multiple">Using Multiple Fonts in the Runtime</a>
   <ul>
       <li><a href="#win32">Specifying Fonts on Win32 Platform</a>
       <li><a href="#filenames">Font file names</a>
       <li><a href="#win32-fontfiles">Win32 Font Files</a>
       <li><a href="#solaris">Specifying Fonts on Solaris Platform</a>
   </ul>
   <li><a href="#testing">Testing for correct xlfd strings in the <code>font.properties</code> files</a>
   <ul>
       <li><a href="#scalable">Note about scalable fonts</a>
       <li><a href="#solaris-fontfiles">Solaris Font Files</a>
       <li><a href="#exclusion">Exclusion ranges</a>
   </ul>
   <li><a href="#converter">The Charset Converter</a>
   <ul>
       <li><a href="#converter1">Step 1. Create fontcharset Converter</a>
       <li><a href="#converter2">Step 2. Add Font and Converter to Properties File</a>
   </ul>
   <li><a href="#debugging">Debugging font.properties files</a>
</ul>


<p>

This document explains how to add Asian and other language fonts to the Java
Runtime by editing the font.properties files.

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

<p>The Java 2 SDK for Win32 platforms supports TrueType and Postscript
Type1 fonts. The Java 2 SDK
for Solaris supports scalable outline fonts that can be handled by an X11
server, such as F3, Type1, and TrueType.

<p>

<a name="naming"></a>
<h2>Naming of the font.properties Files</h2>
<blockquote>


There are several <code>font.properties</code> files that come bundled
with the Java 2 SDK. You can find these files in the directory
<code>../lib</code> 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, the default
<code>font.properties</code> file has no suffix on its file name, as
follows:

<blockquote>

<pre>
font.properties
</pre>

</blockquote>

However, different operating systems have different fonts installed so there
is a provision to read font properties files with the operating system
version embedded in the name.  For instance, Solaris 2.5.1 does not have
support for TrueType fonts so the font properties file,
<code>font.properties.5.5.1</code>, will include only F3 fonts.  Thus,
we first look for a file named:

<block quote>

<pre>
font.properties.&lt;osVersion&gt;
</pre>

</block quote>

where <code>&lt;osVersion&gt;</code> is the version returned by
System.getProperty("os.version") for most systems.  On Windows NT, this
method is overridden to return NT4.0 instead of 4.0 to distinguish between
NT and 95.

<p>

However, if your environment is Japanese, Korean, Chinese, or Traditional
Chinese, then you must use the <code>font.properties</code> 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:

<blockquote>

<pre>
font.properties.&lt;locale&gt;
</pre>

</blockquote>

where <code>locale</code> is one of:

<blockquote>

<pre>
ja

ko

zh

zh_TW

..
</pre>

</blockquote>

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

<p>
NOTE:  The <code>&lt;locale&gt;</code> is actually comprised of
<code>&lt;language&gt;_&lt;region&gt;_&lt;encoding&gt;</code> where
<p>
<code>&lt;language&gt</code> is the string returned from
<code>System.getProperty("user.language")</code>
<p>
<code>&lt;region&gt;</code> is the string returned from
<code>System.getProperty("user.region")</code>
<p>
<code>&lt;encoding&gt;</code> is the string returned from
<code>System.getProperty("file.encoding")</code>

<p>

This <code>font.properties.&lt;locale&gt;</code> name can be augmented
by the operating system version also.  To sum up, the font properties
files are searched in the following order:

<blockquote>

<pre>

font.properties.&lt;language&gt;_&lt;region&gt;_&lt;encoding&gt;.&lt;osVersion&gt;
font.properties.&lt;language&gt;_&lt;region&gt;_&lt;encoding&gt;
font.properties.&lt;language&gt;_&lt;region&gt;.&lt;osVersion&gt;
font.properties.&lt;language&gt;_&lt;region&gt;
font.properties.&lt;language&gt;_&lt;encoding&gt;.&lt;osVersion&gt;
font.properties.&lt;language&gt;_&lt;encoding&gt;
font.properties.&lt;language&gt;_&lt;osVersion&gt;
font.properties.&lt;language&gt;
font.properties.&lt;encoding&gt;.&lt;osVersion&gt;
font.properties.&lt;encoding&gt;
font.properties.&lt;osVersion&gt;
font.properties

</pre>

</blockquote>

<p>

</blockquote>

<a name="using"></a>
<h2>Using the font.properties File</h2>
<blockquote>


You must work with the <code>font.properties</code> file to add fonts
to the Java Runtime. The <code>font.properties</code> 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 logical fonts:

<ul>

       <li>Serif</li>

       <li>Sans-serif</li>

       <li>Monospaced</li>

       <li>Dialog</li>

       <li>DialogInput</li>

</ul><p>

and the following font styles:

<ul>
<li>plain</li>
<li>bold</li>
<li>italic</li>
<li>bolditalic</li>

</ul>
<p>
The <code>font.properties</code> file defines certain information about
the fonts for your platform. This includes aliases, such as:

<blockquote>

<pre>
alias.timesroman=serif

alias.helvetica=sansserif
</pre>

</blockquote>

NOTE: This is a bad example since timesroman and helvetica are actual font
names and in the Java 2 Platform, we no longer alias these names to a virtual font. Do not use names "Times", "Helvetica", for serif, sans serif, respectively, etc.

<p>
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:


<pre>
  &lt;virtual font name&gt;.&lt;style&gt;.&lt;index number&gt; = &lt;platform font name&gt;, attributes
</pre>


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.
<p>
In the Java 2 Platform, the full matrix of virtual font name and style must be complete.
For example, you must have <code>serif</code>, <code>serif.bold</code>
<code>serif.italic</code>, <code>serif.bolditalic</code>.  Note that
<code>serif></code> is equivalent to <code>serif.plain</code>.  All names
in this file are case-insensitive.
<p>
For example, in the Solaris <code>font.properties</code> file in JDK1.1,
the <code>serif</code> entries are as follows:

<blockquote>
<pre>
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
</pre>

</blockquote>

As you can see, only the first entry of "serif.plain", "serif.italic",
"serif.bold" and "serif.bolditalic" were specified. The second and third entry
of the font would default to "serif.1" and "serif.2" in each case (since the
same two fonts were used in each of the "serif" fonts styles). However, in the
Java 2 SDK font.properties, the entire matrix must be specified:

<blockquote>
<pre>
serif.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.italic.1=-urw-itc zapfdingbats-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific
serif.italic.2=--symbol-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific

serif.bold.0=-linotype-times-bold-r-normal--*-%d-*-*-p-*-iso8859-1
serif.bold.1=-urw-itc zapfdingbats-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific
serif.bold.2=--symbol-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific

serif.bolditalic.0=-linotype-times-bold-i-normal--*-%d-*-*-p-*-iso8859-1
serif.bolditalic.1=-urw-itc zapfdingbats-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific
serif.bolditalic.2=--symbol-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific

</pre>
</blockquote>

As mentioned earlier, the key value for the <code>plain</code> style,
<code>plain</code> does not need to be
specified (<code>serif.0</code> defaults to the <code>plain</code> style),
however <code>italic</code>, <code>bold</code> or <code>bolditalic</code>
must be specified for those styles.

<p>

</blockquote>

<a name="adding"></a>
<h2>Adding Locale-Specific Fonts to the Java Runtime</h2>
<blockquote>


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

<a name="adding1"></a>
<h3>Step 1: Install the Font</h3>

<p>

First, you must install the locale-specific font (for example, 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.

<a name="adding2"></a>
<h3>Step 2: Copy the Font</h3>

<p>

Once you have installed the fonts on your system, copy the font description
that you are interested in to <code>font.properties</code>. The easiest
way to add one Asian font is to rename the
</code>font.properties.&lt;locale&gt;</code> file to be the new
<code>font.properties</code> file. The locale symbol represents the font
name that you are interested in.

No editing is required when you replace <code>font.properties</code>
with </code>font.properties.&lt;locale&gt;</code> because
</code>font.properties.&lt;locale&gt;</code> is a superset of
<code>font.properties</code>.

These are the locale symbols that specify the different font properties files:

<a name="locale"></a>
<h3>Locale Symbols for Fonts</h3>

<table border=1>

<tr><td>Font Name <td><code>font.properties</code>
Symbol</td></tr>

<tr><td>Japanese <td><code>ja</code></td></tr>

<tr><td>Korean <td><code>ko</code></td></tr>

<tr><td>Chinese <td><code>zh</code></td></tr>

<tr><td>Traditional Chinese <td><code>zh_TW</code></td></tr>

</table>
</b>
<p>
Thus, to use the the Korean font, you copy or rename
<code>font.properties.ko</code> to
<code>font.properties</code>.

</blockquote>

<a name="multiple"></a>
<h2>Using Multiple Fonts in the Runtime</h2>
<blockquote>


It is possible to use more than one Asian font in your runtime. To do this,
you must edit the <code>font.properties</code> file. This section describes
the edits you need to make to the file to use multiple Asian fonts.

<a name="win32"></a>
<h3>Specifying Fonts on Win32 Platform</h3>

<p>

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

<ul>

       <li>Arial</li>

       <li>WingDings</li>

       <li>Symbol</li>

</ul>

<p>

In addition, the descriptions for these serif fonts in the
<code>font.properties</code> file are as follows:

<blockquote>

<pre>

serif.0=Arial,ANSI_CHARSET

serif.1=WingDings,SYMBOL_CHARSET,NEED_CONVERTED

serif.2=Symbol,SYMBOL_CHARSET,NEED_CONVERTED

</pre>

</blockquote>

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
the index for that font.

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

<p>The first argument is the face name of the Win32 native font. Each line
names a particular font. For example, the line for <code>serif.0</code>
names the font Arial, while the line for <code>serif.2</code>
names the font Symbol.

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

<p>The third argument, if present, is <code>NEED_CONVERTED</code>. 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 <code>NEED_CONVERTED</code> argument
must have a corresponding fontcharset entry, which indicates the charset
converter to use to convert the Unicode string.

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

<blockquote>

<pre>

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

fontcharset.serif.2=sun.awt.CharToByteSymbol

</pre>

</blockquote>

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

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

<p>NOTE: In the current implementation of the Java 2 Platform,
<code>NEED_CONVERTED</code> is not used.

<p>
<a name="filenames"></a>
<h3> Font file names</h3>
To reduce initialization time, there is now a way to specify the mapping
between logical font name to physical font name.  For instance:
<blockquote>
<pre>
filename.Arial=ARIAL.TTF
filename.Arial_Bold=ARIALBD.TTF
filename.Arial_Italic=ARIALI.TTF
filename.Arial_Bold_Italic=ARIALBI.TTF
</pre>
</blockquote>
The first entry shows the mapping between the font name <code>Arial</code>
and the physical font name, <code>ARIAL.TTF</code>.  The next entries
show the mapping for Arial with the different styles applied.  This
shortens the initialization time since we don't have to open every font
file to find a font of that particular name.

<a name="win32-fontfiles"></a>
<h3>Win32 Font Files</h3>

<p>

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

<blockquote>

<pre>

/lib/font.properties

/lib/font.properties.ar

/lib/font.properties.iw

/lib/font.properties.ja

/lib/font.properties.ko

/lib/font.properties.ru

/lib/font.properties.th

/lib/font.properties.zh

/lib/font.properties.zh.NT4.0

/lib/font.properties.zh_TW

</pre>

</blockquote>

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

<a name="solaris"></a>
<h3>Specifying Fonts on Solaris Platform</h3>

<p>

In the Java 2 SDK, the fonts specified in the font.properties file should reference
scalable fonts. This does not mean that the scalable font will always be
used when a specific font point size is requested however. The way in which
X11 works is that given an xlfd string such as
<p>
<pre>
       -adobe-courier-bold-o-normal--10-100-75-75-m-60-iso8859-1
</pre>
<p>
the Xserver will first look for a scalable font that matches the entries found
in the xlfd string (for font foundry, font family, style, slant, encoding, etc).
However, it then will continue to look for a bitmap font which matches this
xlfd string exactly, for this specific pixel/point size (in this case 10 pt).
If one is found, then X11 will return the bitmap directly read from the bitmap
font file which is used rather than a bitmap generated from the data
found in the scalable font file.
<p>
For example, the <code>serif</code> font on an English Solaris (2.6+)
platform consists of the following fonts:
<p>
<blockquote>
<pre>
serif.0=-monotype-times new roman-regular-r---*-%d-*-*-p-*-iso8859-1
serif.1=-urw-itc zapfdingbats-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific
serif.2=-*-symbol-medium-r-normal-*-*-%d-*-*-p-*-adobe-symbol

serif.italic.0=-monotype-times new roman-regular-i---*-%d-*-*-p-*-iso8859-1
serif.italic.1=-urw-itc zapfdingbats-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific
serif.italic.2=-*-symbol-medium-r-normal-*-*-%d-*-*-p-*-adobe-symbol

serif.bold.0=-monotype-times new roman-bold-r---*-%d-*-*-p-*-iso8859-1
serif.bold.1=-urw-itc zapfdingbats-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific
serif.bold.2=-*-symbol-medium-r-normal-*-*-%d-*-*-p-*-adobe-symbol

serif.bolditalic.0=-monotype-times new roman-bold-i---*-%d-*-*-p-*-iso8859-1
serif.bolditalic.1=-urw-itc zapfdingbats-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific
serif.bolditalic.2=-*-symbol-medium-r-normal-*-*-%d-*-*-p-*-adobe-symbol
</pre>
</blockquote>
<p>

These lines from the Solaris <code>font.properties</code> 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
<code>serif.0</code>, <code>serif.1</code>, and
<code>serif.2</code>. In addition, these lines indicate that the serif font
with the style italic consists of <code>serif.italic.0</code>,
<code>serif.italic.1</code>, and <code>serif.italic.2</code>.

<p>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:

<blockquote>

<pre>

fontcharset.serif.0=sun.io.CharToByte8859_1

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

fontcharset.serif.2=sun.awt.CharToByteSymbol

</pre>

</blockquote>

For example, the line:

<blockquote>

<pre>

fontcharset.serif.0=sun.io.CharToByte8859_1

</pre>

</blockquote>

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

<p>

</blockquote>

<a name="testing"></a>
<h2>Testing for correct xlfd strings in the <code>font.properties</code> files</h2>
<blockquote>

The reason scalable fonts should be specified however is because Java2D can
only perform certain operations on scalable fonts, such as generating outlines.
Currently the Java2D code can recognize scalable fonts such as TrueType, Type1
or F3. Therefore, when entering xlfd strings in the font.properties file,
look for these types of fonts installed on the system and specify those.
TrueType fonts will typically have the file extension of "ttf". Type 1 fonts
will have either "pfa" or "pfb" as the extension. F3 fonts will have the
extension "f3b". On Solaris 2.6, in "C" locale, with all packages installed,
you can find fonts of these formats in:
<p>
<blockquote>
<pre>
       Type1:    /usr/openwin/lib/X11/fonts/Type1
       TrueType: /usr/openwin/lib/X11/fonts/TrueType
       F3:       /usr/openwin/lib/X11/fonts/F3
</pre>
</blockquote>
<p>
In other locales, the fonts will be installed in a directory such as
/usr/openwin/lib/locale/<locale>. For example, in JA locale, under
/usr/openwin/lib/locale/ja, there are fonts installed in:
<p>
<blockquote>
<pre>
       TrueType: /usr/openwin/lib/locale/ja/X11/fonts/TT
       F3:       /usr/openwin/lib/locale/ja/X11/fonts/F3
</pre>
</blockquote>
<p>
The location of the font files may be different depending on locale (that
is, may not always be /usr/openwin/lib/locale/&lt;locale&gt;/X11/fonts), but
they are typically under the /usr/openwin/lib/locale/&lt;locale&gt; directory
somewhere.
<p>
Once the scalable fonts have been located, look at the "fonts.dir" file that
will be found in the directory with the scalable font files. This file lists
all of the valid xlfd strings for the fonts contained in that directory. For
example, in the "fonts.dir" file located in the
<code>/usr/openwin/lib/locale/ja/X11/fonts/TT</code>
directory, there is an entry like this:
<p>
<pre>
       HG-MinchoL.ttf -ricoh-hg mincho l-medium-r-normal--0-0-0-0-m-0-jisx0208.1983-0
</pre>
<p>
In the xlfd string, you will see 4 consecutive zero (0) values. These indicate
the pixel size, point size, resolution x and resolution y values. When copying
this xlfd string into a font.properties entry, remember to replace the point
size (the second "0") with a "%d" which is later replaced with a specific point
size when the font is used. Also, replace the other "0" values with "*"
(asterisk) to indicate that any value may match this field. So, for example,
if the above font was to be used as entry for the "serif" font specified in
the font.properties file, it would look like:
<p>
<pre>
       serif.1=-ricoh-hg mincho l-medium-r-normal--*-%d-*-*-m-*-jisx0208.1983-0
</pre>
<p>
When the font is actually used, the point size specified when the Java "Font"
object is created is used (the "%d" is replaced with this value), and the
font is initialized for use at that point size.
<p>
One way to verify that the xlfd strings that you have entered in the
font.properties file are correct is to try and display that font using "xfd".
"xfd" is an X11 application in /usr/openwin/bin that displays all of the
characters found in a font. To run the application, you specify the font
(as an xlfd string). To verify an xlfd entry in a font.properties file,
replace the "%d" with a valid point size such as 120 (for 12 pt), 140
(for 14 pt), 160 (for 16 pt), etc. (xlfd point size is 10 times the
"pixel size" where "pixel size" is normally thought of as the font point
size). So, in the above example, with the "serif.1" entry for a Japanese
font.properties file, to verify that this xlfd string is correct, run:
<p>
<pre>
       % xfd -fn "-ricoh-hg mincho l-medium-r-normal--*-140-*-*-m-*-jisx0208.1983-0"
</pre>
<p>
If the xlfd string is incorrect, "xfd" will not display a window, and will
exit immediately and print out an error message like this:
<p>
<pre>
       Warning: Cannot convert string "&lt;xlfd string&gt;" to type FontStruct
       xfd:  no font to display
</pre>
<p>
If the xlfd string is correct, a window will appear with all of the characters
specified in that font. If there are more than 256 characters, then only the
first 256 are displayed, but the user may look through all entries by hitting
the "NextPage" button displayed on the application.
<p>

<a name="scalable"></a>
<h3>Note about scalable fonts</h3>
<p>
Remember that the fonts specified in the font.properties files must be in
one of the formats mentioned above (TrueType, Type1 or F3). If there no
fonts installed on the system in those formats, then Java2D will not find
any valid fonts so operations like drawString ("some Text") will not work.
<p>
There are bugs in the X server for Type1 fonts (more problems
in 2.5.1 than 2.6) so it is preferable to avoid Type1 fonts also.

<a name="solaris-fontfiles"></a>
<h3>Solaris Font Files</h3>

<p>

The font properties files provided by the Java 2 SDK are located in
the <tt>jre/lib</tt> directory.  (In the Java 2 Runtime Environment,
the they are located in the <tt>lib</tt> directory.)  As of version
1.3, the font properties files included with the
SDK and Runtime Environment are the following.

<blockquote>

<pre>

font.properties
font.properties.5.5.1
font.properties.ISO8859_15_FDIS
font.properties.UTF8
font.properties.UTF8.5.6
font.properties.UTF8.5.7
font.properties.cs
font.properties.el
font.properties.hu
font.properties.ja
font.properties.ja.5.5.1
font.properties.ko
font.properties.ko.5.5.1
font.properties.ko.5.6
font.properties.ko.5.7
font.properties.ko_KR_UTF8
font.properties.ko_KR_UTF8.5.6
font.properties.ko_KR_UTF8.5.7
font.properties.lt
font.properties.lt_ISO8859_13
font.properties.lv
font.properties.lv_ISO8859_13
font.properties.pl
font.properties.ru
font.properties.tr
font.properties.zh_CN_UTF8
font.properties.zh_EUC_CN
font.properties.zh_EUC_CN.5.5.1
font.properties.zh_GBK
font.properties.zh_TW_Big5
font.properties.zh_TW_Big5.5.5.1
font.properties.zh_TW_Big5.5.6
font.properties.zh_TW_EUC_TW
font.properties.zh_TW_EUC_TW.5.5.1
font.properties.zh_TW_UTF8
</pre>
</blockquote>
<p>

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


<a name="exclusion"></a>
<h3>Exclusion ranges</h3>
As mentioned in the previous sections, the numbers after the virtual font name
indicate the order in which the actual fonts are searched to find the
requested glyph.  There are sometimes overlapping ranges of glyphs
in each of the physical fonts that comprise the virtual font.  An
exclusion range can be added to limit the range in which glyphs are
searched in a physical font.
<p>
For example, in the Solaris font.properties.ja file, the following describes
a monospaced font:
<blockquote>
<pre>
monospaced.plain.0=-morisawa-gothic medium bbb-medium-r-normal-sans-*-%d-*-*-m-*-jisx0201.1976-0
monospaced.plain.1=-morisawa-gothic medium bbb-medium-r-normal-sans-*-%d-*-*-m-*-jisx0208.1983-0
monospaced.plain.2=-morisawa-gothic medium bbb-medium-r-normal-sans-*-%d-*-*-m-*-jisx0201.1976-0
monospaced.plain.3=-urw-itc zapfdingbats-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific
monospaced.plain.4=--symbol-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific
</pre>
</blockquote>
The corresponding exclusion range is as follows:
<blockquote>
<pre>
exclusion.monospaced.0=0080-ffff
</pre>
</blockquote>
<p>
Thus, glyphs in the range, Unicode 0x0080 to Unicode 0xffff, are excluded
from the first font in the virtual font so the subsequent fonts
(monospaced.plain.1, monospaced.plain.2, monospaced.plain.3,
monospaced.plain.4) will be searched for those glyphs.

</blockquote>

<a name="converter"></a>
<h2>The Charset Converter</h2>
<blockquote>


The <code>charset</code> converter converts Unicode, or Java string
encoding, to the index of the font. For font drawing, the runtime
environment uses
the <code>charset</code> converter that is the subclass of
<code>sun.io.CharToByteConverter</code>.

<p>To add your own font to the runtime environment, you need to create a
<code>charset</code> converter and specify it in the
<code>font.properties file</code>.

<p>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
<code>fontcharset</code> converter class. Second, you specify your font
name and converter class name in the <code>font.properties file</code>
file.

<a name="converter1"></a>
<h3>Step 1. Create fontcharset Converter</h3>

<p>

This is the Java code for creating the <code>fontcharset</code> converter.

<blockquote>

<pre>
package mypkg.converter;

import sun.io.CharToByte8859_1;
import sun.io.CharToByteConverter;
import sun.io.ConversionBufferFullException;

public class CharToByteMyFont extends sun.io.CharToByte8859_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";
  }
}
</pre>

</blockquote>

<a name="converter2"></a>
<h3>Step 2. Add Font and Converter to Properties File</h3>

<p>

You must first set the font name in the <code>font.properties</code>
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.

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

<blockquote>

<pre>
serif.3=&lt;your own font name&gt;
</pre>

</blockquote>

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

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

<blockquote>

<pre>
fontcharset.serif.3=mypkg.converter.CharToByteMyfont
</pre>

</blockquote>

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
<code>classpath</code> must include the class path to the converter. In our
example, we must be sure that the class
<code>mypkg.converter.CharToByteMyfont</code> is visible to the Java
Runtime. The simplest way to do this is to put this class under your
<code>$JDK_HOME/classes/myown/package</code> directory.

<p>

</blockquote>

<a name="debugging"></a>
<h2> Debugging font.properties files</h2>
<blockquote>

The best way to debug a custom font.properties file is by comparing it
with an existing file.  First, you need to find the correct font.properties
file (based on osversion, region, encoding, language).  Then if you check
the differences between your file and the standard file, the only differences
should be the fonts you wish to substitute (and possibly other fields related
to the new fonts, such as exclusion ranges).
<p>
Next, run a test such as SymbolTest in demo/applets/SymbolTest and see if
the standard logical fonts are displayed.

</blockquote>

<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
</body>
</html>