You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

How to change the font setting in Gecko from the Embedding Application

Author:

Frank Yung-Fong Tang ftang@netscape.com
Roy Yokoyama yokoyama@netscape.com
Shanjian Li shanjian@netscape.com

 

Introduction

Gecko is shipping with a set of default font preferences. This documentation describes how to change the font setting from a Gecko embedding client in two saturations:

  1. The embedding client want to ship with a different default font setting
  2. The embedding client want to change the setting of the font through an API

 

The Common Part:

Each font setting in Gecko is defined by one or more preferences. And each preference is form by a preference key and a preference value.

 

In order to change the font setting, you need to know the following:

  1. The font name in Unicode
  2. The generic font family setting you wants to change the setting.
  3. The language group you want to change the setting
  4. The pattern of the preference key for the font setting

 

We will not talk about the font name in Unicode in this document and assume the reader know how to get the value they want to set to. And we will discuss the rest in the following section.

Generic Font-family Name:

CSS define 5 different generic font families. The Gecko font setting divides the font setting based on that. The concept of generic font-family name is defined in the CSS2 specification. See the CSS2 specification for the detail information about the definition of those values:

 

  • “serif”
  • “sans-serif”
  • “monospace”
  • “cursive”
  • “fantasy”

 

Language Group:

To simplified the font setting, instead of having one set of setting per charset (or document encoding), we map several charset into one “language group” so different charset for the same language group will use the same font preference setting. For example, Shift_JIS, EUC-JP, and ISO-2002-JP are map to the Japanese language group

Currently, we defined the following language group:

 

  • “x-western”: for document encoded in Western European encodings
  • “ja”: for document encoded in Japanese encodings
  • “zh-CN”: for document encoded in Simplified Chinese encodings
  • “zh-TW”: for document encoded in Traditional Chinese encodings
  • “ko”: for document encoded in Korean encodings
  • “ar”: for document encoded in Arabic encodings
  • “el”: for document encoded in Greek encodings
  • “he”: for document encoded in Hebrew encodings
  • “th”: for document encoded in Thai encodings
  • “tr”: for document encoded in Turkish encodings
  • “x-baltic”: for document encoded in Baltic encodings
  • “x-central-euro”: for document encoded in Central European encodings
  • “x-cyrillic”: for document encoded in Cyrillic encodings
  • “x-unicode”: for document encoded in Unicode encodings

 

The information about mapping charset into one of these language groups are defined in the file intl/uconv/src/charsetData.properties in the mozilla source tree. Also, the English (or other translated) name of these language groups are listed under the English (or other language) locale dtd file: xpfe/components/prefwindow/resources/locale/en-US/pref-fonts.dtd

Basically, the name of the language group falls into one of the three categories:

 

  1. An ISO 639 two character code in lower case: If the font setting makes sense to only one language. For example: “ja” for Japanese
  2. An ISO 639 two character code in lower case, plus a “-“ to connect an ISO 3166 code in upper case: If the font setting make sense to only one language used in a particular region/country: for example: “zh-TW” for Chinese used in Taiwan.
  3. “x-“ and a code that we invented: This is used when the font setting make sense for a group of languages.
  4.  

We may define additional language group in the near future to support other writing system such Indic languages, Armenian, and Georgian, etc.

 

The Font Preference Key Patten:

The font preference use the following pattern to generate the preference key to control the font name:

 

“font.name.$generic.$languagegroup”

 

Where $generic is the 5 generic font-family name and the $languagegroup is the language group.

 

Change the Default Setting

The font preferences are stored into different preferences file according to the platform. Embedding customers could change the default setting by change the value in those files. However, the embedding client needs to make sure the following most important issue:

 

Encoding of font name in the Preference File should be UTF-8 and UTF-8 only: The content of the preferences file is encoded in UTF-8 encoding. Therefore, all font names in that file need to be encoded in UTF-8.

 

File locations for default preferences file in the mozilla source tree:

 

 

Call the Preference API

The embedding client can (or should) also change the font setting according to the user’s action. In order to add such function, the developer needs the following steps:

  1. Get the font name in Unicode
  2. Decide which CSS generic font-family name and language group the user want to set to.
  3. Format the font preference key according to the information in 2
  4. Call the preference API to set the value

 

Since 1 and 2 depend on the specific application framework, we won’t discuss here. The step to perform step 3 is also very simple. This section only discusses the issues you need to aware about for step 4.

 

The API you should use to set the font preferences is 
·        nsIPrefBranch:: setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue)
·        nsIPrefBranch::setCharPref
(in string aPrefName, in string aValue)

 

How to call setComplexValue to set the font name?

This is the only choice you have in the JavaScript to set the font preference correctly because currently this is the only Unicode safe method in the nsIPrefBranch to pass Unicode string.

 

Here is a sample of calling it from the JavaScript; you can find this code in editor/ui/composer/content/editorUtilities.js:

 

aPrefObj.setComplexValue(aPrefName, Components.interfaces.nsISupportsString, str);

How to call setCharPref to set the font name?

The 2nd argument of setCharPref is a type of “string” instead of a “wstring”, this mean there are no way you can call this API from JavaScript and do the correct thing because string is not safe to pass Unicode data from JavaScript. However, if you are using C/C++ code, you can call this API for font name and still do the right thing. What you need to make sure is the aValue have to be encoded in “UTF-8” before pass to this API.

 

How to get the nsIPrefBranch?

References: