Common Desktop Environment: Internationalization Programmer's Guide

Font Management

The desktop uses font lists to display text. A font defines a set of glyphs that represent the characters in a given character set. A font set is a group of fonts that are needed to display text for a given locale or language. A font list is a list of fonts, font sets, or a combination of the two, that may be used. Motif has convenience functions to create a font list.

Font List Structure

The desktop requires a font list for text display. A font list is a list of font structures, font sets, or both, each of which has a tag to identify it. A font set ensures that all characters in the current language can be displayed. With font structures, the responsibility for ensuring that all characters can be displayed rests with the programmer (including converting from the code set of the locale to glyph indexes).

Each entry in a font list is in the form of a {tag, element} pair, where element can be either a single font or a font set. The application can create a font list entry from either a single font or a font set. For example, the following code segment creates a font list entry for a font set:

char font1[] =
 		"-adobe-courier-medium-r-normal--10-100-75-75-M-60";  
font_list_entry = XmFontListEntryLoad (displayID, font1,
  		XmFONT_IS_FONTSET, "font_tag");

The XmFontListEntryLoad() function loads a font or creates and loads a font set. The following are the four arguments to the function:

displayID: Display on which the font list is to be used.
fontname: A string that represents either a font name or a base font name list, depending on the nametype argument.
nametype: A value that specifies whether the fontname argument refers to a font name or a base font name list.
tag: A string that represents the tag for this font list entry.

If the nametype argument is XmFONT_IS_FONTSET, the XmFontListEntryLoad() function creates a font set in the current locale from the value in the fontname argument. The character sets of the fonts specified in the font set are dependent on the locale. If nametype is XmFONT_IS_FONT, the XmFontListEntryLoad() function opens the font found in fontname. In either case, the font or font set is placed into a font list entry.

The following code example creates a new font list and appends the entry font_list_entry to it:

XmFontList font_list;  
XmFontListEntry font_list_entry;
  		.
  		.
font_list = XmFontListAppendEntry (NULL, font_list_entry);  
XmFontListEntryFree (font_list_entry);

Once a font list has been created, the XmFontListAppendEntry() function adds a new entry to it. The following example uses the XmFontListEntryCreate() function to create a new font list entry for an existing font list.

XFontSet font2;  
char *font_tag;  
XmFontListEntry font_list_entry2;
  		.
  		.  
font_list_entry2 = XmFontListEntryCreate (font_tag,
  		 XmFONT_IS_FONTSET, (XtPointer)font2);

The font2 parameter specifies an XFontSet returned by the XCreateFontSet() function. The arguments to the XmFontListEntryCreate() function are font_tag, XmFONT_IS_FONTSET, and font2, which are the tag, type, and font, respectively. The tag and the font set are the {tag, element} pair of the font list entry.

To add this entry to the font list, use the XmFontListAppendEntry() function again, only this time, its first parameter specifies the existing font list.

font_list = XmFontListAppendEntry(font_list, font_list_entry2); 
XmFontListEntryFree(font_list_entry2);

Font Lists Examples

The syntax for specifying a font list in a resource file depends on whether the list contains fonts, font sets, or both.

Obtaining a Font

To obtain a font, specify a font and an optional font list element tag.

If the tag is present, it should be preceded by an = (equal sign).
If the tag is not present, do not use an = (equal sign).

Entries specifying more than one font are separated by a , (comma).

Obtaining a Font Set

To obtain a font set, specify a base font list and an optional font list element tag.

If the tag is present, it should be preceded by a : (colon) instead of an = (equal sign).
If the tag is not present, the colon must still be present as this is what distinguishes a font from a font set in the resource declaration.

Fonts specified in the base font list are separated by a ; (semicolon). Entries specifying more than one font set are separated by a , (comma).

Specifying a Font When the Font List Element Tag Is Absent

If the font list element tag is not present, the default XmFONTLIST_DEFAULT_TAG is used. Here are some examples.

Specifying a font using the default font list element tag:

*fontList: fixed 
*fontList: \  
-adobe-courier-medium-r-normal--10-100-75-75-M-60-iso8859-1

Specifying a font list element tag:
```
*fontList: fixed=ROMAN, 8x13bold=BOLD
```
Specifying two fonts, one with the default font list element tag and one with an explicit tag:
```
*fontList: fixed, 8x13bold=BOLD
```

Specifying a Font Set When the Font List Element Tag Is Absent

If the font list element tag is not present, the default XmFONTLIST_DEFAULT_TAG is used. Here are some examples of specifying a font set.

Let Xlib select the fonts without specifying a font list element tag:
```
*fontList: -dt-application-medium-r-normal-*-m*-*-*-*-m-*
```
Let Xlib select the fonts and specify a font list element tag as MY_TAG:
```
*fontList: -dt-application-medium-r-normal-*-m*-*-*-*-m*:MY_TAG
```
Let Xlib select the fonts, specify a font list element tag for bold fonts, and use the default font list element tag for the others:
```
*fontList:	-dt-application-medium-r-normal-*-m*-*-*-*-m-*:,\
  -dt-application-medium-r-normal-style2-m*-*-*-*-m-*:BOLD
```

Font List Syntax

The XmFontList() data type can contain one or more entries that are associated with one of the following elements:

XFontStruct: An X font that can be used to draw text encoded in the charset of the font, that is, font-encoded text.
XFontSet: A collection of XFontStruct fonts used to draw text encoded in a locale, that is, localized text.

The following syntax is used by the string-to-XmFontList converter:

XmFontList     := <fontentry> {', 'fontentry}   

fontentry			:= <fontname><fontid>
  			| <baselist><fontsetid>   

baselist			:= <fontname>{';'<fontname>}   

fontsetid			:= ':'<string> | <defaultfontset>   

fontname			:= <XLFD string>  

fontid			:= '='<string> | <defaultfont>   

XLFD string			:= refer to XLFD Specification  
defaultfont			:= NULL  
defaultfontset			:= ':'NULL  
string			:= any character from ISO646IRV, except newline

A fontentry with a given XmFontList can specify either a font or a font set. In either case, the ID (fontid or fontsetid) can be referenced by a segment within a compound string (XmString).

Both defaultfont and defaultfontset can define the default fontentry, yet there can only be one default per XmFontList.

The XmFONTLIST_DEFAULT_TAG identifier always references the default fontentry when XmString is drawn. If the default fontentry is not specified, the first fontentry is used to draw.

The resource converter operates under a single locale so that all font sets created are associated with the same locale.

Note -

Some implementations reserve the code set name of a locale as a special charset ID (fontsetid and fontid) within an XmFontList string. For this reason, application developers are cautioned not to use code set names if they want their applications to be portable across platforms.