C H A P T E R  22



X-Designer helps you to make use of the special features that X and Motif provide to assist in developing applications that can be used in different languages. Although internationalization is a complex subject, this chapter points you in the direction of those areas that you will need to examine in order to fully internationalize your software.

In order to type text of languages other than your own, you will need an X server which supports that language. You can find out if this is the case by checking whether the locale is present on your system. See Locale Name for some hints on how to find out.

What Is the Problem?

If your application is to be used by speakers of another language (even if that other language is British English rather than American English) you cannot assume that they understand your language and conventions. Apart from the variation in language, the use and style of addresses, date and time formats, personal names, even paper sizes may be very different from yours.

Scripts, in particular, can constitute a vast difference in the appearance and behavior of your application. Some languages, such as Korean, Japanese and Chinese, are ideographic. They do not have an alphabet as understood in Roman languages. Each word is represented in a graphical form. The fonts used to display such a script need to be able to handle thousands of these characters. This problem is discussed further in Creating International Text.

Other languages, such as Hebrew and Thai are alphabetic but still totally unlike Roman scripts. Some letters change according to context. There are often no spaces to distinguish words and some languages are written right to left while others are written left to right.

Even languages which appear to be very similar, such as French, English and German, involve differences in the symbols (or diacritics) used with letters and in the way in which letters are changed from lowercase to uppercase and vice versa.

X11 does assist you in addressing these problems by providing FontSets. These are explained in Font Sets. Also explained in this chapter is the mechanism by which input methods, required by non-alphabetic scripts, can be used in your application.

Although Japanese is used in most examples in this chapter, the principles are the same for any language.

It must be stressed here that this chapter aims to introduce you to the large area of internationalization and to explain how this is supported by X-Designer. You are strongly advised to refer to additional documentation for more in-depth information. This includes system documentation, Motif documentation and, where necessary, books such as those listed in Appendix F.


Before you begin to address the issue of internationalization with regard to your application, you will need to understand how to set up your environment for a particular location. This involves an understanding of locales. A locale is an ANSI-C concept. It is a name that is used to identify a set of local information. For example, the locale might be set to be "en_UK" to denote that the location is the U.K. with English as the language, "en_US" for English as used in the U.S., or "ja" for Japanese. The setting of a locale makes certain C library functions operate in different ways, e.g. defining the sorting order, or date format.

Locale Name

You need to know the system name of the locale you are wishing to use and then set the LANG environment variable correspondingly so that applications can work out which language they should be displaying. Note that the name of the locale may differ depending on which system you are using. For a list of locale names supported by your UNIX system, look in the directory /usr/lib/locale. This will contain a directory for every language available. The directory names are used as the locale name, which is also the name you should use for the LANG environment variable. Type:

locale -a 

to list all locales currently installed on your system.

Specifying the Locale

To run X-Designer with internationalization support, you must set an appropriate locale. Do this by setting the LANG environment variable before running your X server, for example:

setenv LANG ja

This tells X to use Japanese for its display fonts and keyboard input, if Japanese is installed on your system. The value of the environment variable may be different on your system, as explained in Locale Name.

For a language such as Japanese, which uses an input method in-between the keyboard and a text widget, you must make sure that you are running the appropriate version of X-Designer (in this case Japanese). This is because it is the presence of the Japanese fonts, in combination with the LANG environment variable, which indicates to the X server that an input method is required.

Font Sets

Part of a locale's definition includes a specification of the font encodings required in order to display all possible text. For example, the Japanese locale requires that fonts with codesets ISO 8859-1, JIS X0208-1983 and JIS X0201-1976 be present in order to display all text in the Japanese language because Japanese contains Roman characters, Japanese alphabet characters (kana) and ideographic characters (Kanji). A FontSet is a collection of Fonts that contains all the required character sets for the current locale.


The FontList is a collection of Fonts which is used for drawing labels in multiple fonts and styles. FontLists are specific to Motif whereas FontSets are defined by X.

For example, in order to specify that a string contains both bold and italic, you create a compound string with markers indicating which font (bold or italic) to use where. This is easily achieved in the X-Designer XmString editor (see Compound Strings). To do so, however, you need to define a Font Object in the Font Editor (see Setting Fonts) which contains a list of fonts--one bold and one italic. This is your FontList. Each Font in the FontList is tagged with the name you specify in the Font Editor. These tags are included in the compound string to tell the X server which font to use.

What Is the Connection Between FontSets and FontLists?

In order to incorporate FontSets, Motif has extended its definition of a FontList so that each entry in a FontList can be either a single Font (FontStruct) or a FontSet.

X-Designer simplifies this by presenting all the Fonts in a FontSet as straightforward members of the FontList. However, when you set the FontSet toggle in the Font Selection dialog, you are indicating to X-Designer that this Font is a member of a FontSet. Internally X-Designer gives all members of a FontSet the same FontList tag. Motif then collects together all Fonts with the same FontList tag as members of a FontSet.

See Simple Font Objects for more information on font objects and Creating a Complex Font Object for an explanation of FontLists.

Example of the Use of FontSets

The following exercise illustrates the use of FontSets.

The Japanese locale described above requires these three encodings:

1. Pop up the Font selection dialog.

2. Enter a Font object f1 and a tag name t1.

3. Set the "Font set" toggle on.

4. Use the Reg Filter Menu to show all ISO 8859-1 fonts.

5. Select an appropriate ISO 8859-1 font and press bind.

Note that you should press the Default button as the tag name if you wish this FontSet to be used by default, otherwise you will have to provide code to make sure that the FontSet is used by your widget.

At this point, Xlib warns you that you have a FontSet that does not have sufficient encodings charsets to display text in the current locale. This is correct, since you still have two fonts to do.

 FIGURE 22-1 Missing Charsets Warning

Warning dialog with text: "Missing charsets in String to FontSet conversion".

 FIGURE 22-2 Initial Font in FontSet

Font Selection dialog showing the example font object and fontlist tag binding.

6. Select a font with JIS X0208-1983 registry and bind it.

Xlib issues another warning of missing charsets.

7. Select a font with JIS X0201-1976 registry and bind it.

This time Xlib does not warn you because the FontSet is now complete.

Font object entries can be deleted and re-bound regardless of whether or not they are part of a FontSet. A FontList can have many entries which can be either FontSets or simple fonts. To achieve this, specify different Fontlist tags and set the "Font set" toggle as appropriate. The following example shows a single font object that has three entries: t1, big and t2. t1 and t2 are complete FontSets for the ja locale; big is a simple font.

 FIGURE 22-3 A Font Object With Multiple Entries

Font object and fontlist tag portion of the Font Selection dialog showing multiple fontlist tags bound to a single font object.

Creating International Text

For a language such as Japanese, Chinese or Korean, more characters can be displayed than there are keys on the keyboard, or numbers that can be represented by 8 bits. In addition, text displayed by Japanese symbols must be mixed with Roman numerals and Roman text. These problems are addressed by coding the text in a special way. Instead of the familiar ASCII mapping, multi byte text strings are used in order to allow for the larger set of characters in these languages. Multiple characters in the text signify a single character from the matching font. The way in which one- and multi-byte characters are distinguished depends on the encoding. Such languages also have a one-to-many mapping of sound (as may be typed on the keyboard) and ideographic character. To resolve this, an input method is provided.

Languages such as Hebrew and Arabic also require an input method because the letters change according to the position in the word and vowels are written around the consonant.

If an input method is required and you are running an appropriately localized version of X-Designer, a special key sequence switches into using the input method when you enter text into a text field. The method converts the characters typed into corresponding characters in the target language.

Using an Input Method in X-Designer

To enter non-English text into any text input area in X-Designer first of all make sure that you fulfil the following requirements:

The following example illustrates how to type text in a language which requires an input method. The language used is Japanese.

If you are using CDE:

single-step bulletSet the locale in the dialog box when you log in and then log in as usual.

If you are not using CDE:

single-step bulletSet the LANG environment variable to "ja"

If you are using OpenWindows you do not need to do anything else. If, however, you are using the Motif Window Manager, you should start the input method server by typing htt at the command line prompt.

1. Start your X server

Whenever a window containing a text field has the current focus, a status line appears at the bottom of the window. This is a text area displaying the current input mode.

Whether you are using CDE or not, the following instructions are the same:

2. Start X-Designer.

You can read in a saved design or start a new one. Make sure that you have a Text widget.

3. Select a Text widget, invoke its resource panel and select the "Label" field.

4. Type Ctrl-Space. Check your input method documentation for the correct key.

The status line changes to indicate that you may now type kana.

5. Type Ctrl-W.

The kana is converted to Kanji and a candidate list is displayed allowing you to select the Kanji you want to enter into the text field.

6. Click on an item in the candidate list and then press <Space> to send the selected Kanji to X-Designer.

The procedure for other languages is similar--first, set the LANG environment variable, start your X server, then invoke X-Designer. For some languages and on some systems you may also need to start an input method or server. Refer to your system documentation to check whether this is necessary. The input method will appear whenever a window with a text area has the current focus.

For more information on international text on Sun platforms, see your Sun documentation.

Localized Input in Your Application

The previous section described how to enter non-ASCII text into X-Designer (for example into the label resource). This section describes how to enter localized text in your generated application. Note that the term "converted text" is used. This means any text on the screen which differs from that which appears on a standard keyboard.

How Text Is Converted

The X toolkit does most of the work for you. What you need to do is to indicate to the X toolkit that a particular text widget will be receiving non-ASCII text. This is accomplished by fulfilling these criteria:

If the second condition above is true, the text widget makes a request to the enclosing Shell to establish a connection to the input method. The X toolkit then takes over, diverting text input for that text widget to the input method and returning to the text widget the resulting converted text.

Setting up a Text Widget to Receive Converted Text

You can see from above that in order for a text widget in your application to use an input method, all you have to do is to make sure that the text widget has a FontList specified for it which includes a FontSet matching the locale at creation time. The simplest way to do this is to use X-Designer to specify a font object containing an appropriate FontSet and use that as the font resource for the widget. The following steps illustrate this:

1. Create a dialog with a Text child.

2. Designate the Shell as an ApplicationShell.

3. Select the Text and pop up the resource panel.

4. Click on the Font button.

5. Specify a font object with an appropriate FontSet

Refer to Example of the Use of FontSets for a description of how to do this. Remember to give the FontSet fonts the "Default" tag. If you do not, the X server may not realize that an input method is required.

6. Generate code. Compile.

7. Run the generated application on an X server with support for the language specified for the Text widget.

Seeing the Input Method in the Dynamic Display

Although the above works correctly for your generated application, there is a drawback. X-Designer always creates the widget before resources are applied to it, even on reset or paste. Therefore, to see the input method working in the dynamic display window, you must force the font to be specified at creation time. This is best accomplished by setting the textFontList resource on a parent Bulletin Board or Shell widget. Obviously, this has the disadvantage that all the child text widgets have the input method.

To see a text widget working with an input method from within X-Designer, use the following steps.

1. Create a dialog with a Form child.

2. Designate the Shell as an ApplicationShell.

3. Select the Form and pop up the "Fonts" page of its resource panel.

4. Click on the "Text font" button.

5. Specify a font object with an appropriate FontSet

Refer to Example of the Use of FontSets for a description of how to do this. Remember to give the FontSet fonts the "Default" tag. If you do not, the X server may not realize that an input method is required.

6. Create a Text widget child.

7. Add other widgets as required.

 FIGURE 22-4 A Simple Dialog With Input Method Attached

A simple dialog showing an OptionMenu, TextField and two PushButtons with an input method at the bottom of the dialog.

The default main() program includes a call to XtSetLanguageProc(), which initializes the locale handling routines. If you are writing your own main() program, you must insert a call to this routine if you are using any internationalization features. Add the following line to the beginning of your main() routine:

XtSetLanguageProc((XtAppContext)0, (XtLanguageProc)0, (XtPointer)0);

Setting the Application Font Resource

When using international text in X-Designer the text will not appear correctly in the dynamic display or generated application unless the appropriate FontList resource is set for the language you are using.

A useful way to implement the correct FontList settings on an application-wide basis is to use loose bindings to declare a FontList resource binding as in the following example:


Note - The line breaks in the above example have been inserted for clarity--if you are editing a resource file you must make sure that there are no line breaks, otherwise the resource setting will be ignored.

where XApplication is the class name of your application. This example sets some Japanese fonts. The above example resource can be found in $XDROOT/src/examples/loose_bindings/ja_fontlist.res and can be loaded into your design via the loose bindings dialog.

See Loose Bindings for details on how to do this.

Using Eight-Bit Characters in Shell Titles

If you intend to use a character with the eighth bit set in the title string of a Shell widget, you must make sure that the titleEncoding resource is set to "STRING". You can do this from within X-Designer by specifying a loose binding which should look like this:

XApplication*titleEncoding:	STRING

(where XApplication is the class name of your application.)

Or this:

*titleEncoding:	STRING

depending on whether you wish the resource binding to apply to all applications (as in the second example) or just your own application. See Loose Bindings for details on how to do this.

Alternatively, if you prefer to "hard code" the setting of this resource in your design, you can set the pre-manage prelude for the main Shell as follows:

XtSetArg ( al[ac], XmNtitleEncoding, XA_STRING ); ac++;

See Shell Pre-manage Prelude for details on adding a pre-manage prelude to a Shell widget.

Unsupported Locales

Using an Input Method in X-Designer describes how you can specify a locale using the LANG environment variable. Providing you are using an appropriate version of X-Designer, you may then use the language of the locale for the strings in the user interface you are designing. If you have set your LANG environment variable to a locale which is not supported by your version of X-Designer, a message is displayed on startup informing you that your LANG setting is unsupported and that it is being coerced to "C". This is the default and is US English. If your X-Designer expects a Latin script[1], it will display and function correctly. The only area where there could be a problem is in strings in the generated code. If the following are true, you will be able to add labels, text strings etc. in the locale you specified:

If, however, any of the above is not true, you will probably not be able to enter or display strings in the specified language.

1 (Footnote) The term "Latin script" here refers to the ISO Latin 1 character set.