HP OpenVMS Systems Documentation

2 Internationalization and the Common Desktop Environment

Locale Management

Font Management

Matching Fonts to Character Sets

Font Objects

Font Set and Font List Syntax

Font Functions

Font Charsets

Default Font Set Per Language Group

Drawing Localized Text

Simple Text

XmString (Compound String)

Inputting Localized Text

Basic Prompts and Dialogs

Input within a DrawingArea Widget

Application-Specific and Language-Specific Intermediate Feedbacks

Text and TextField Widget

Character Input within Customized Widgets Not Using Text[Field] Widgets

XIM Management

XIM Event Handling

XIM Callback

Extracting Localized Text

Resource Files

Message Catalogs

Private Files

Message Guidelines

Message Extraction Functions

XPG4/Universal UNIX Messaging Functions

XPG4 Messaging Examples

Xlib Messaging Functions

Xlib Message and Resource Facilities

Localized Resources

Labels and Buttons

List Resources

Title

Text Widget

Input Method (Keyboards)

Pixmap (Icon) Resources

Font Resources

Operating System Internationalized Functions

Locale Management

All internationalized programs should set the locale desired by the user as defined in the locale environment variables. For programs using the desktop toolkit, the programs call the XtSetLanguageProc() function prior to calling any toolkit initialization function; for example, XtAppInitialize(). This function does all of the initialization necessary prior to the toolkit initialization. For nondesktop programs, the programs call the setlocale() function to set the locale desired by the user at the beginning of the program.

Locale environment variables (for example, LC_ALL, LC_CTYPE, and LANG) are used to control the environment. Users should be aware that the LC_CTYPE category of the locale is used by the X and Xm libraries to identify the locale-specific features used at run time. Yet, the LC_MESSAGES category is used by the message catalog services to load locale-specific text. Refer to "Extracting Localized Text" for more information. Specifically, the fonts and input method loaded by the toolkit are determined by the setting of the LC_CTYPE category.

String encoding (for example, ISO8859-1 or Extended UNIX Code (EUC), in an application's source code, resource files, and User Interface Language (UIL) files) should be the same as the code set of the locale where the application runs. If not, code conversion is required.

All components are shipped as a single, worldwide executable and are required to support the R5 sample implementation set of locales:
US, Western/Eastern Europe, Japan, Korea, China, and Taiwan.

Applications should be written so that they are code-set-independent and include support for any multibyte code set.

The following are the functions used for locale management:

• XtSetLanguageProc()
• setlocale()
• XSupportsLocale()
• XSetLocaleModifiers()

Font Management

• Obtaining the localized text itself

• Selecting the one or more fonts that contain all the glyphs needed to render the characters in the localized text.

Matching Fonts to Character Sets

• Determine the fonts needed
• Specify the necessary fonts
• Determine the charset of a font in a resource file
• Choose multiple fonts per locale

For example:

-adobe-courier-medium-r-normal--24-240-75-75-m-150-iso8859-1

The font charset used by the application to render data depends on the locale you select. Because the font charset of the data changes is based on the choice of locale, the font specification must not be hardcoded by the application. Instead, it should be placed in a locale-specific app-defaults file, allowing localized versions of the app-defaults file to be created.

Further, the font should be specified as a fontset. A fontset is an Xlib concept in which an XLFD is used to specify the fonts. The font charset fields of the XLFD are specified by the Xlib code that creates the fontset and fills in these fields based on the locale that the user has specified.

For many languages (such as Japanese, Chinese, and Korean), multiple font charsets are combined to support single encoding. In these cases, multiple fonts must be opened to render the character data. Further, the data must be parsed into segments that correspond to each font, and in some cases, these segments must be transformed to convert the character values into glyphs indexes. The XFontset, which is a collection of all fonts necessary to render character data in a given locale, also deals with this set of problems. Further, a set of rendering and metric routines are provided that internally take care of breaking strings into character-set-consistent segments and transforming values into glyph indexes. These routines relieve the burden of the application developer, who needs only the user fontsets and the new X11R5 rendering and metric application program interfaces (APIs).

Font Objects

• Font sets
• Fonts
• Font lists

Font Sets

Applications directly using Xlib to render text (as opposed to using XmString functions or widgets) may take advantage of the string-to-fontSet converter provided by Xt. For example, the following code fragment shows how to obtain a fontset when using Xt and when not using Xt:

/* pardon the double negative... means "If using Xt..." */
#ifndef NO_XT
typedef struct {
        XFontSet fontset;
            char *foo;
} ApplicationData,  *ApplicationDataPtr;
static XtResource my_resources[] = {
    { XtNfontSet, XtCFontSet, XtRFontSet, sizeof (XFontSet),
    XtOffset (ApplicationDataPtr, fontset), XtRString,
     "*-18-*"}}
#endif /* NO_XT */
...
#ifdef NO_XT
fontset = XCreateFontSet (dpy, "*-18-*", &missing_charsets,
    &num_missing_charsets. &default_string);
if (num_missing_charsets > 0) {
    (void) fprintf(stderr, "&s: missing charsets.\n",
                    program_name);
    XFreeStringList(missing_charsets);
}
#else
XtGetApplicationResources(toplevel, &data, my_resources,
       XtNumber(my_resources), NULL, 0);
fontset = data.fontset;
#endif /* NO_XT */

Fonts

Font Lists

Font Set and Font List Syntax

Table 2-1 Font Set and Font List Syntax

Here are some examples of font resource specifications:

app_foo*fontList: -adobe-courier-medium-r-normal--24-240-75-75-m-\
150-*:

app_foo*fontList: -adobe-courier-medium-r-normal--18-*; *-gothic-\
*-18-*:

Motif-based applications sometimes need direct access to the font set contained in a font list. For example, an application that uses a DrawingArea widget may want to label one of the images drawn there. The following sample code shows how to extract a font set from a font list. In this example, the tag XmFONTLIST_DEFAULT_TAG looks for the font set because this is the tag that says "codeset of the locale." Applications should use the tag XmFONTLIST_DEFAULT_TAG for any string that could contain localized data.

XFontSet FontList2FontSet( XmFontList fontlist)
{
XmFontContext context;
XmFontListEntry next_entry;
XmFontType type_return = XmFONT_IS_FONT;
char* font_tag;
XFontSet fontset;
XFontSet first_fontset;
Boolean have_font_set = False;

if ( !XmFontListInitFontContext(&context, fontlist)) {
     XtWarning("fl2fs: can't create fontlist context...");
     exit 0;
}

while ((next_entry = XmFontListNextEntry(context) != NULL) {

    fontset = (XFontSet) XmFontListEntryGetFont(next_entry, 
                &type_return);
    if (type_return == XmFONT_IS_FONTSET ) {

        font_tag = XmFontListEntryGetTag(next_entry);

        if (!strcmp(XmFONTLIST_DEFAULT_TAG, font_tag) {
            return fontset;
       }
        /* Remember the 1st fontset, just in case... */
        if (!have_font_set) {
            first_fontset = fontset;
            have_font_set = True;
       }
    }
}
if (have_font_set)
    return first_fontset;
return (XFontSet)NULL;
}

Font Functions

• XCreateFontSet()
• XLocaleOfFontSet()
• XFontsOfFontSet()
• XBaseFontNameListOfFontSet()
• XFreeFontSet()

• XmFontListEntryCreate()
• XmFontListEntryAppend()
• XmFontListEntryFree()
• XmFontListEntryGetTag()
• XmFontListEntryGetFont()
• XmFontListEntryLoad()

Font Charsets

Default Font Set Per Language Group

Yet, when selecting the base font names of a font set for various locales, this task can be difficult because an XLFD font specification consists of 15 fields. For localized usage, the following fields are critical for selecting font sets:

• FAMILY_NAME %F

• WEIGHT_NAME %W

• SLANT %S

• ADD_STYLE %A

• SPACING %SP

Throughout this documentation, the following convention should be used when specifying localized fonts:

-dt-%F-%W-%S-normal-%A-*-*-*-%SP-*

Latin ISO8859-1 Fonts

FOUNDRY

`dt'

FAMILY_NAME

`interface user'
`interface system'
`application'

WEIGHT_NAME

medium or bold

SLANT

r or i

ADD_STYLE

sans or serif

SPACING

p or m

Other ISO8859 Fonts

JIS Japanese Font

FOUNDRY

`dt'

FAMILY_NAME

Gothic or Mincho

WEIGHT_NAME

medium or bold

SLANT

r

ADD_STYLE

*

SPACING

m

KSC Korean Font

FOUNDRY

`dt'

FAMILY_NAME

Totum or Pathang

WEIGHT_NAME

medium or bold

SLANT

r

ADD_STYLE

*

SPACING

m

CNS Traditional Chinese Font

FOUNDRY

`dt'

FAMILY_NAME

Sung and Kai

WEIGHT_NAME

medium or bold

SLANT

r

ADD_STYLE

*

SPACING

m

GB Simplified Chinese Font

FOUNDRY

`dt'

FAMILY_NAME

Song and Kai

WEIGHT_NAME

medium or bold

SLANT

r

ADD_STYLE

*

SPACING

m

Drawing Localized Text

Simple Text

• XmbDrawImageString()
• XmbDrawString()
• XmbDrawText()

• XwcDrawImageString()
• XwcDrawString()
• XwcDrawText()

• XExtentsOfFontSet()
• XmbTextEscapement()
• XmbTextExtents()
• XmbTextPerCharExtents

• XExtentsOfFontSet()
• XwcTextEscapement()
• XwcTextExtents()
• XwcTextPerCharExtents

XmString (Compound String)

More importantly, for interclient communications, the XmStringConvertToCT() function associates a segment tagged as XmFONTLIST_DEFAULT_TAG as being encoded in the code set of the locale. Otherwise, depending on the tag name used, the Xm library may not be able to properly identify the encoding on interclient communications for text data.

A localized string segment inside an XmString can be drawn with a font list having a font set with XmFONTLIST_DEFAULT_TAG. Use of a localized string is recommended for portability.

The following is an example of creating a font list for drawing a localized string:

XmFontList CreateFontList( Display* dpy, char* pattern)
}

SmFontListEntry font_entry;
XmFontList fontlist;
font_entry = XmFontListEntryLoad( dpy, pattern,
                                       XmFONT_IS_FONTSET,
                                       XmFONTLIST_DEFAULT_TAG);

fontlist = XmFontListAppendEntry(NULL, font_entry);
/* XmFontListEntryFree(font_entry); */

if ( fontlist == NULL ) {
      XtWarning("fl2fs: can't create fontlist...");
      exit (0);
}

return fontlist;
}

int main(argc,argv)
int argc;
char **argv;
}
  Display *dpy;            /* Display                 */
  XtAppContext app_context;/*  Application Context    */

  XmFontList fontlist;
  XmFontSet fontset;
  XFontStruct** fontstructs;
  char** fontnames;
  int i,n;

char *progrname;     /* program name without the full pathname */

if (progname=strrchr(argv[0], `/')){
  progname++;
}
else  {
  progname = argv[0];
}

/*    Initialize toolkit and open display.
 */
XtSetLanguageProc(NULL, NULL, NULL);
XtToolkitInitialize():
app_context = XtCreateApplicationContext();
dpy = XtOpenDisplay(app_context, NULL, progname, "XMdemos",
                      NULL, 0, &argc, argv);
if (!dpy) {
    XtWarning("fl2fs: can't open display, exiting...");
    exit(0);
}

fontlist = CreateFontList(dpy, argv[1] );
fontset = FontList2FontSet( fontlist );

/*
 * Print out BaseFontNames of Fontset
 */
n = XFontsOfFontSet( fontset, &fontstructs, &fontnames);

  printf("Fonts for %s is %d\n", argv[1], n);

  for (i = 0 ; i < n ; ++i ) printf("font[%d} - %s\n", i,\
                                           fontnames[i] );

  exit(1);

}

labelString: Japanese string

*fontList:-dt-interface system-medium-r-normal-L*-*-*-*-*-*-*:

• XmStringCreateLocalized()
• XmStringDraw()
• XmStringDrawImage()
• XmStringDrawUnderline()

• XmStringCreateLtoR()
• XmStringSegementCreate()

Inputting Localized Text

The local input method means that the input method is built in the Xlib. It is typically used for a language that can be composed using simple rules and that does not require language-specific features. The network-based input method means that the actual input method is provided as separate servers, and Xlib communicates with them through the XIM protocol to do the language-specific composition.

Basic Prompts and Dialogs

Input within a DrawingArea Widget

Application-Specific and Language-Specific Intermediate Feedbacks

The core Xlib provides the common set of interfaces that allow an application to display intermediate feedback during preediting. By registering the application's callbacks and setting the preediting style to XNPreeditCallbacks, an application can get the intermediate preediting data from the input method and can draw whatever it needs.

Applications intended to do sophisticated language processing may recognize extensions within a specific XIM implementation and its input method engines. Such applications are on the leading edge and will require familiarity with details of the XIM functions.

Text and TextField Widget

Most XmText functions are based on the number of characters, not on the number of bytes. For example, all XmTextPosition() function positions are character positions, not byte positions. The XmTextGetMaxLength() function returns the number of bytes. When in doubt, remember that positions are always in character units.

The width of a Text or TextField widget is determined by the resource value of XmNcolumns. But, this value means the number of the widest characters in the font set, not the number of bytes or columns. For example, suppose that you have selected a variable-width font for the Text widget. The character i may have a width of 1 pixel, while the character W may have a width of 7 pixels. When a value of 10 is set for XmNcolumns, this is considered a request to make the Text widget wide enough to be able to display at least 10 characters. So the Text widget must use the width of the widest character to determine the pixel width of its core widget. With this example, it may be able to display 10 W characters in the widget, or 70 i characters. This structure for XmNcolumns may cause problems in locales whose code set is a multibyte and a multicolumn encoding. As such, this value should be set within a localized resource.

The following section identifies the set of functions available for applications that are used to manage input methods. For applications that use the Text and TextField widgets, refer to "Input Method (Keyboards)".

Character Input within Customized Widgets Not Using Text[Field] Widgets

Although the XmIm functions are shipped in all implementations of Motif 1.2, the functions are not documented in Motif 1.2. OSF has announced its intention to augment and document the XmIm functions for Motif 2.0. The functions described here are the Motif 1.2 XmIm functions.

Following are the XmIm functions you can safely use in a Motif 1.2-based application. The formal description of the parameters and types can be found in the Xm.h header file.

Function Name

Description

XmImRegister()

Performs XOpenIM() and queries the input method for supported styles.

XmImSetValues()

Negotiates and selects the preedit and status styles.

XmImSetFocusValues()

Creates the XIC, if one does not exist. Notifies the input method that the widget has gained the focus. Sets the values passed to the XIC.

XmImUnsetFocus()

Notifies the input method that the widget has lost the focus.

XmImMbLookupString()

Xm equivalent of XmbLookupString(); converts one or more key events into a character. Return value is identical to XmbLookupString().

XmImUnregister()

Disconnects the input method and the widget, allowing connection to a new input method. Does not necessarily close the input method (implementation-dependent).

Argument Name

Data Type

XmNbackground

Pixel

XmNforeground

Pixel

XmNbackgroundPixmap

Pixmap

XmNspotLocation

XPoint

XmNfontList

Motif fontlist

XmNlineSpace

int (pixel height between consecutive baselines)

• Before initializing the toolkit, the application should call XtSetLanguageProc(NULL, NULL, NULL) to initialize the locale.

• After creating the widget where character input is desired, the application should call XmImRegister(widget) to open the input method and establish a connection.

• After establishing a connection to the input method, the application should pass the initial XIC values to the input method by calling XmImSetValues() and passing all of the values listed above. This function takes an arg_list and a number_args argument. The arglist is loaded by calling XtSetArg().

• Add an event handler, through the XtAddEventHandler() function, for the manager widget of the widget obtaining input from the input method. The event handler is for the FocusChangeMask mask. The handler should call XmImSetFocusValues() when gaining focus and should call XmImUnsetFocus() when losing focus. When setting focus for the input method, pass the full set of values listed above.

• Add a DestroyCallback for the widget obtaining input from the input method. In the destroy callback, call XmImUnregister() to notify the input method that you are breaking the connection between the widget and the input method.

• Use XmImSetValues() to notify the input method any time one or more of the input method values listed above change (for example, spotLocation).

XIM Management

Function Name

Description

XOpenIM()

Establishes a connection to an input method.

XCloseIM()

Removes a connection to an input method previously established with a call to XOpenIM().

XGetIMValues()

Queries the input method for a list of properties. Currently, the only standard argument in Xlib is XNQueryInputStyle.

XDisplayOfIM()

Returns the display associated with an input method.

XLocaleOfIM()

Returns a string identifying the locale of the input method. There are no standard strings; the value returned by this call is implementation-defined.

XCreateIC()

Creates an input context. The input context contains both the data required (if any) by an input method and the information required to display that data.

XDestroyIC()

Destroys an input context, freeing any associated memory.

XIMOfIC()

Returns the input method currently associated with a given input context.

XSetICValues()

Passes zero or more values to an input context to control input of character data, or control display of preedit or status information. A table of all valid input context value arguments can be found in the X11R5 specification.

XGetICValues()

Queries an input context to get zero or more input context values. A table of all valid input context value arguments can be found in the X11R5 specification.

XIM Event Handling

Function Name

Description

XmbLookupString()

Converts keypress events into characters.

XwcLookupString()

Converts keypress events into wide characters.

XmbResetIC()

Resets an input context to its initial state. Any input pending on that context is deleted. Returns the current preedit value as a char* string. Depending on the implementation of the input method, the return value may be NULL.

XwcResetIC()

Resets an input context to its initial state. Any input pending on that context is deleted. Returns the current preedit value as a wchar_t* string.

XFilterEvent()

Allows the input method to process any incoming events to the clients before the application processes them.

XSetICFocus()

Notifies the input method that the focus window attached to the specified input context has received keyboard focus.

XUnsetICFocus()

Notifies the input method that the specified input context has lost the keyboard focus and that no more input is expected on the focus window attached to that context.

XIM Callback

Table 2-2 XIM Callbacks

Extracting Localized Text

This section describes how the user, the application developer, and the implementation combine to establish the language environment of the application. Two general approaches to localizing applications are also discussed. The following three methods can be used:

• Resource files
• Message catalogs
• Private files

Resource Files

Also note that the Xm library functions do not depend on the LC_MESSAGE category when specifying the location from which localized resources are loaded. Refer to the XtSetLanguageProc() man page for more information.

Message Catalogs

The messaging support is based on both the XPG4 and System V Release 4 (SVR4) interfaces for accessing message catalogs.

Private Files

Message Guidelines

Message Extraction Functions

There are two sets of message extraction functions in the desktop environment: XPG4 functions and Xlib functions.

XPG4/Universal UNIX Messaging Functions

• catopen()
• catgets()
• catclose()

XPG4 Messaging Examples

Message Source File

example.msg file:
$quote "
$ every message catalog should have a beginning set number.
$set 1 This is the set 1 of messages
1 "Hello world\n"
2 "Good Morning\n"
3 "example: 1000.220 Read permission is denied for the file
%s.\n"
$set 2
1 "Howdy\n"

Generation of Catalog File

gencat example example.msg

Accessing the Catalog in a Program

#include <locale.h>
#include <nl_types.h>
char *MF_EXAMPLE = "example.cat"

main()
{
        nl_catd catd;
        int error;

        (void)setlocale(LC_ALL, "");

        catd = catopen(MF_EXAMPLE, 0);
            /* Get the message number 1 from the first set.*/
        
        printf( catgets(catd,1,1,"Hello world\n") );
            /* Get the message number 1 from the second set.*/
        
        printf( catgets(catd, 2, 1,"Howdy\n") );
            /* Display an error message.*/
        
        printf( catgets(catd, 1, 4,"example: 100.220
            Permission is denied to read the file %s.\n") ,
            MF_EXAMPLE);
        catclose(catd);
}

Xlib Messaging Functions

• XrmPutFileDatabase()
• XrmGetFileDatabase()
• XrmGetStringDatabase()
• XrmLocaleOfDatabase()

Xlib Message and Resource Facilities

In general, for any error or warning messages to be displayed to the user through a system environment toolkit widget or gadget, externalize the messages through message catalogs.

For dialog messages to be displayed through a toolkit component, externalize the messages through localized resource files. This is done in the same way as localizing resources, such as the XmLabel and XmPushButton classes' XmNlabelString resource or window titles.

For example, if a warning message is to be displayed through an XmMessageBox widget class, the XmNmessageString resource cannot be hardcoded within the application source code. Instead, the value of this resource must be retrieved from a message catalog. For an internationalized application expected to run in different locales, a distinct localized catalog must exist for each of the locales to be supported. In this way, the application need not be rebuilt.

Localized resource files can be put in the /usr/lib/X11/%L/appdefaults subdirectories, or they can be pointed to by the XENVIRONMENT environment variable. The %L variable is replaced with the name of the locale used at run time.

Localized Resources

Labels and Buttons

Only the widget class resources are listed here; subclasses of these widgets are not listed. For example, the XmDrawnButton widget class does not introduce any new resources that are localized. However, it is a subclass of the XmLabelWidget widget class; therefore, its accelerator resource, acceleratorText resource, and so on, are also localized and should not be hardcoded by an application.

Table 2-3 Localized Resources

Note that the XmRowColumn widget has additional string resources that may be localized. These resources are listed in the XmRowColumn man page, under the heading "Simple Menu Creation Resource Set." As the title implies, these resources affect only RowColumn widgets created with the XmCreateSimpleMenu() function. The resources affected are: *buttonAccelerators, *buttonAcceleratorText, *buttonMnemonics, *optionLabel, and *optionMnemonic. These resources are not included in Table 2-3 because they are rarely used and apply to RowColumn only when creating a simple menu.

List Resources

Table 2-4 Resources Used for Reading Lists

Title

Table 2-5 Resources Used for Setting Titles and Icon Names

Text Widget

Table 2-6 Locale-Sensitive Text[Field] Resources

Input Method (Keyboards)

Table 2-7 Localized Resources for Input Method Customization

Pixmap (Icon) Resources

Table 2-8 Pixmap Resources

A pixmap is a screen image that is stored in memory so that it can be recalled and displayed when needed. The desktop has a number of pixmap resources that allow the application to supply pixmaps for backgrounds, borders, shadows, label and button faces, drag icons, and other uses. As with text, some pixmaps may be specific to particular language environments; these pixmaps must be localized.

The desktop maintains caches of pixmaps and images. The XmGetPixmapByDepth() function searches these caches for a requested pixmap. If the requested pixmap is not in the pixmap cache and a corresponding image is not in the image cache, the XmGetPixmapByDepth() function searches for an X bitmap file whose name matches the requested image name. The XmGetPixmapByDepth() function calls the XtResolvePathname() function to search for the file. If the requested image name is an absolute path name, that path name is the search path for the XtResolvePathname() function. Otherwise, the XmGetPixmapByDepth() function constructs a search path in the following way:

• If the XBMLANGPATH environment variable is set, the value of that variable is the search path.

• If XBMLANGPATH is not set but XAPPLRESDIR is set, the XmGetPixmapByDepth() function uses a default search path with entries that include $XAPPLRESDIR, the user's home directory, and vendor-dependent system directories.

• If neither XBMLANGPATH nor XAPPLRESDIR is set, the XmGetPixmapByDepth() function uses a default search path with entries that include the user's home directory and vendor-dependent system directories.

Because there is no string-to-pixmap converter supplied by default, pixmaps are generally set by the application at creation time by first retrieving the pixmap with a call to XmGetPixmap(). XmGetPixmap() uses the current locale to determine where to locate the pixmap. (See the XmGetPixmap() man page for a description of how locale is used to locate the pixmap.)

Font Resources

Table 2-9 Localized Font Resources

Operating System Internationalized Functions

Applications should perform proper locale management with the assumption that a locale may have from 1 to 4 bytes per coded character.

Table 2-10 Base Operating System Internationalized Functions

Table 2-10 Base Operating System Internationalized Functions (continued)