How to change the font setting in Gecko from the Embedding Application
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:
- The embedding client want to ship with a different default font setting
- 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:
- The font name in Unicode
- The generic font family setting you wants to change the setting.
- The language group you want to change the setting
- 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:
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:
- An ISO 639 two character code in lower case: If the font setting makes sense to only one language. For example: “ja” for Japanese
- 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.
- “x-“ and a code that we invented: This is used when the font setting make sense for a group of languages.
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:
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:
- Windows: modules/libpref/src/win/winpref.js
- MacOS : modules/libpref/src/mac/macprefs.js
- Linux & *nix: modules/libpref/src/unix/unix.js
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:
- Get the font name in Unicode
- Decide which CSS generic font-family name and language group the user want to set to.
- Format the font preference key according to the information in 2
- 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)(in string aPrefName, in string aValue)
How to call setComplexValue to set the font name?
aPrefObj.setComplexValue(aPrefName, Components.interfaces.nsISupportsString, str);
How to call setCharPref to set the font name?
How to get the nsIPrefBranch?
- This question is beyond the scope of this document. Basically, you need to use nsIPrefService to get the nsIPrefBranch Read “Gecko Embedding API Reference”, “Gecko Supported preferences for embedding purposes” and other documents in http://www.mozilla.org/projects/embedding/ for more details.
- Gecko Supported preferences for embedding purposes
- Gecko Embedding API Reference
- ISO 639:1988 (E/F) "Code for the representation of names of languages".
- Codes from ISO 3166