Common Desktop Environment: Internationalization Programmer's Guide

Drawing Localized Text

A compound string is a means of encoding text so that it can be displayed in many different fonts without changing anything in the program. The desktop uses compound strings to display all text except that in the Text and TextField widgets. This section explains the structure of a compound string, the interaction between it and a font list (which determines how the compound string is displayed), and focuses on those aspects that are important to the internationalization process.

Compound String Components

A compound string is an internal encoding, consisting of tag-length-value segments. Semantically, a compound string has components that contain the text to be displayed, a tag (called a font list element tag) that is matched with an element of a font list, and an indicator denoting the direction in which it is to be displayed.

A compound string component can be one of the following four types:

A font list element tag.
- The font list element tag XmFONTLIST_DEFAULT_TAG indicates that the text is encoded in the code set of the current locale.
- Other font list element tags are used later to match text with particular entries in a font list.
A direction identifier.
The text of the string. For internationalized applications, the text falls into two broad categories: either the text requires localized treatment or it does not.
A separator.

The following describes each of the compound string components:

Font list element tag: Indicates a string value that correlates the text component of a compound string to a font or a font set in a font list.
Direction: Indicates the relationship between the order in which characters are entered on the keyboard and the order in which the characters are displayed on the screen. For example, the display order is left-to-right in English, French, German, and Italian, and right-to-left in Hebrew and Arabic.
Text: Indicates the text to be displayed.
Separator: Indicates a special form of a compound string component that has no value. It is used to separate other segments.

The desktop uses the specified font list element tag identified in the text component to display the compound string. A specified font list element tag is used until a new font list element tag is encountered. The desktop provides a special font list element tag, XmFONTLIST_DEFAULT_TAG, that matches a font that is correct for the current code set. It identifies the default entry in a font list. See "Compound Strings and Font Lists" for more information.

The direction segment of a compound string specifies the direction in which the text is displayed. Direction can be left-to-right or right-to-left.

Compound Strings and Resources

Compound strings are used to display all text except that in the Text and TextField widgets. The compound string is set into the appropriate widget resource so that it can be displayed. For example, the label for the PushButton widget is inherited from the Label widget, and the resource is XmNlabelString, which is of type XmString. This means that the resource expects a value that is a compound string. A compound string can be created with a program or defined in a resource file.

Setting a Compound String Programmatically

An application can set this resource programmatically by creating the compound string using the XmStringCreateLocalized() compound string convenience function.

This function creates a compound string in the encoding of the current locale and automatically sets the font list entry tag to XmFONTLIST_DEFAULT_TAG.

The following code segment shows one way to set the XmNlabelString resource for a push button using a program.

#include <nl_types.h>  
Widget		button;  
Args		args[10];  
int		n; 
 XmString button_label;  
nl_msg my_catd;  
(void)XtSetLanguageProc(NULL,NULL,NULL);
  		.
  		.  
button_label = XmStringCreateLocalized (catgets(my_catd, 1, 1,
  		 	"default label"),
  			XmFONTLIST_DEFAULT_TAG);   

/* Create an argument list for the button */  
n = 0;  
XtSetArg (args[n], XmNlabelString, button_label); n++;   

/* Create and manage the button */  
button = XmCreatePushButton (toplevel, "button", args, n);  
XtManageChild (button);  
XmStringFree (button_label);

Setting a Compound String in a Defaults File

In an internationalized program, the label string for the button label should be obtained from an external source. For example, the button label can come from a resource file instead of the program. For this example, assume that the push button is a child of a Form widget called form1.

*form1.button.labelString:
Push Here

Here, the desktop's string-to-compound-string converter produces a compound string from the resource file text. This converter always uses XmFONTLIST_DEFAULT_TAG.

Compound Strings and Font Lists

When the desktop displays a compound string, it associates each segment with a font or font set by means of the font list element tag for that segment. The application must have loaded the desired font or font set, created a font list that contains that font or font set and its associated font list element tag, and created the compound string segment with the same tag.

The desktop follows a set search procedure when it binds a compound string to a font list entry in this way:

The desktop searches the font list for an exact match with the font list element tag specified in the compound string. If it finds a match, the compound string is bound to that font list entry.

If this does not provide a binding between the compound string and the font list, the desktop binds the compound string to the first element in the font list, regardless of its font list element tag.

For backward compatibility, if an exact match is not found, a value of XmFONTLIST_DEFAULT_TAG in either a compound string or a font list matches the tag that results from creating a compound string or font list entry with a tag of XmSTRING_DEFAULT_CHARSET.

Figure 4-1 shows the relationships between a compound string, a font set, and a font list when the font list element tag is set to something other than XmFONTLIST_DEFAULT_TAG.

Figure 4-1 Relationships between compound strings, font sets, and font lists when the font list element tag is not XmFONTLIST_DEFAULT_TAG

The following example shows how to use a tag called tagb.

XFontSet     *font1;  
XmFontListEntry			font_list_entry; 
 XmFontList font_list;  
XmString label_text;
char**			missing;
int			missing_cnt;
char*			del_string;
char *tagb;				/* Font list element tag */
char *fontx;				/* Initialize to XLFD or font alias */
char *button_label;				/* Contains button label text */
  		.
  		.  
font1 = XCreateFontSet (XtDisplay(toplevel), fontx, & missing,
  		& missing_cnt, & def_string);  
font_list_entry = XmFontListEntryCreate (tagb, XmFONT_IS_FONTSET,
  		(XtPointer)font1);  
font_list = XmFontListAppendEntry (NULL, font_list_entry);  
XmFontListEntryFree (font_list_entry);   
label_text = XmStringCreate (button_label, tagb);

The XCreateFontSet() function loads the font set and the XmFontListEntryCreate() function creates a font list entry. The application must create an entry and append it to an existing font list or create a new font list. In either case, use the XmFontListAppendEntry() function. Because there is no font list in place, the preceding code example has a NULL value for the font list argument. The XmFontListAppendEntry() function creates a new font list called font_list with a single entry, font_list_entry. To add another entry to font_list, follow the same procedure but supply a nonnull font list argument.

Figure 4-2 shows the relationships between a compound string, a font set, and a font list when the font list element tag is set to XmFONTLIST_DEFAULT_TAG. In this case, the value field is locale text.

Figure 4-2 Relationships between compound strings, font sets, and font lists when a font list element tag is set to XmFONTLIST_DEFAULT_TAG

Here, the default tag points to Font_Set_C, which in turn identifies the fonts needed to display the characters in the language.

Text and TextField Widgets and Font Lists

The Text and TextField widgets display text information. To do so, they must be able to select the correct font in which to display the information. The Text and TextField widgets follow a set search pattern to find the correct font as follows:

The widget searches the font list for an entry that is a font set and has a font list element tag of XmFONTLIST_DEFAULT_TAG. If a match is found, it uses that font list entry. No further searching occurs.

The widget searches the font list for an entry that specifies a font set. It uses the first one found.

If no font set is found, the widget uses the first font in the font list.

Using a font set ensures that there are glyphs for every character in the locale.