Common Desktop Environment: Internationalization Programmer's Guide

Locale Management

The following defines support for the locale mechanism that controls all locale-dependent Xlib and Common Desktop Environment functions.

X Locale Management

X locale supports one or more of the locales defined by the host environment. The Xlib conforms to the American National Standards Institute (ANSI) C library, and the locale announcement method is the setlocale() function. This function configures the locale operation of both the host C library and Xlib. The operation of Xlib is governed by the LC_CTYPE category; this is called the current locale.

The XSupportsLocale() function is used to determine whether the current locale is supported by X.

The client is responsible for selecting its locale and X modifiers. Clients should provide a means for the user to override the clients' locale selection at client invocation. Most single-display X clients operate in a single locale for both X and the host-processing environment. They configure the locale by calling three functions: setlocale(), XSupportsLocale(), and XSetLocaleModifiers().

The semantics of certain categories of X internationalization capabilities can be configured by setting modifiers. Modifiers are named by implementation-dependent and locale-specific strings. The only standard use for this capability at present is selecting one of several styles of keyboard input methods.

The XSetLocaleModifiers() function is used to configure Xlib locale modifiers for the current locale.

The recommended procedure for clients initializing their locale and modifiers is to obtain locale and modifier announcers separately from one of the following prioritized sources:

A command-line option
A resource
The empty string (" ")

The first of these that is defined should be used.

Note -

When a locale command-line option or locale resource is defined, the effect should be to set all categories to the specified locale, overriding any category-specific settings in the local host environment.

Locale and Modifier Dependencies

The internationalized Xlib functions operate in the current locale configured by the host environment and in the X locale modifiers set by the XSetLocaleModifiers() function, or in the locale and modifiers configured at the time some object supplied to the function was created. For each locale-dependent function, Table 5-1 lists locale and modifier dependencies.

Table 5-1 Locale and Modifier Dependencies


Locale from...	Affects the Function...	In the...
	Locale Query/Configuration
`setlocalle`	`XSupportsLocale` `XSetLocaleModifiers`	Locale queried Locale modified
	Resources
`setlocale`	`XrmGetFileDatabase` `XrmGetStringDatabase`	Locale of XrmDatabase
XrmDatabase	`XrmPutFileDatabase` `XrmLocaleOfDatabase`	Locale of XrmDatabase
	Setting Standard Properties
`setlocale`	`XmbSetWMProperties`	Encoding of supplied returned text (some `WM_ property` text in environment locale)
`setlocalle`	`XmbTextPropertyToTextList` `XwcTextPropertyToTextList` `XmbTextListToTextProperty` `XwcTextListToTextProperty`	Encoding of supplied/returned text
	Text Input
`setlocalle`	`XOpenIM`	XIM input method
XIM	`XCreateIC` `XLocaleOfIM`, etc.	XIC input method configuration Queried locale
XIC	`XmbLookupText` `XwcLookupText`	Keyboard layout Encoding of returned text
	Text Drawing
`setlocale`	`XCreateFontSet`	Charsets of fonts in XFontSet
XFontSet	`XmbDrawText`, `XwcDrawText`, etc. `XExtentsOfFontSet`, etc. `XmbTextExtents`, `XwcTextExtents`, etc.	Locale of supplied text Locale of supplied text Locale-dependent metrics
	Xlib Errors
`setlocalle`	XGetErrorDatabaseText XGetErrorText	Locale of error message

Clients can assume that a locale-encoded text string returned by an X function can be passed to a C library function, or the string result of a C library function can be passed to an X function, if the locale is the same at the two calls.

All text strings processed by internationalized Xlib functions are assumed to begin in the initial state of the encoding of the locale, if the encoding is state-dependent. All Xlib functions behave as if they do not change the current locale or X modifier setting. (This means that any function, provided within a library either by Xlib or by the application, that changes the locale or calls the XSetLocaleModifiers() function with a nonnull argument, must save and restore the current locale state on entry and exit.) Also, Xlib functions on implementations that conform to the ANSI C library do not alter the global state associated with the mblen(), mbtowc(), wctomb(), and strtok() ANSI C functions.

Xt Locale Management

Xt locale management includes the following two functions:

XtSetLanguageProc()
XtDisplayInitialize()

XtSetLanguageProc

Before the initialization of the Xt Toolkit, applications should normally call the XtSetLanguageProc() function with one of the following functions:

XtSetLanguageProc (NULL, NULL, NULL)

Note -

The locale is not actually set until the toolkit is initialized (for example, by way of the XtAppInitialize() function). Therefore, the setlocale() function may be needed after the XtSetLanguageProc() function and the initializing of the toolkit (for example, if calling the catopen() function).

Resource databases are created in the current process locale. During display initialization prior to creating the per-screen resource database, the Intrinsics call to a specified application procedure to set the locale according to options found on the command line or in the per-display resource specifications.

The callout procedure provided by the application is of type XtLanguageProc, as in the following syntax:

typedef String(*XtLanguageProc)(displayID,languageID, clientdata);  
Display *displayID;  
String languageID;  
XtPointer clientdata;

displayID: Passes the display.
languageID: Passes the initial language value obtained from the command line or server per-display resource specifications.
clientdata: Passes the additional client data specified in the call to the XtSetLanguageProc() function.

The language procedure allows an application to set the locale to the value of the language resource determined by the XtDisplayInitialize() function. The function returns a new language string that is subsequently used by the XtDisplayInitialize() function to establish the path for loading resource files. This string is cached and is the locale of the display.

Initially, no language procedure is set by the intrinsics. To set the language procedure for use by the XtDisplayInitialize() function, use the XtSetLanguageProc() function:

XtLanguageProc XtSetLanguageProc(applicationcontext, procedure, clientdata) 
XtAppContext applicationcontext;  
XtLanguageProc procedure;  
XtPointer clientdata;

applicationcontext: Specifies the application context in which the language procedure is to be used or specifies a null value.
procedure: Specifies the language procedure.
clientdata: Specifies additional client data to be passed to the language procedure when it is called.

The XtSetLanguageProc() function sets the language procedure that is called from the XtDisplayInitialize() function for all subsequent displays initialized in the specified application context. If the applicationcontext parameter is null, the specified language procedure is registered in all application contexts created by the calling process, including any future application contexts that may be created. If the procedure parameter is null, a default language procedure is registered. The XtSetLanguageProc() function returns the previously registered language procedure. If a language procedure has not yet been registered, the return value is unspecified; but if this return value is used in a subsequent call to the XtSetLanguageProc() function, it causes the default language procedure to be registered.

The default language procedure does the following:

Sets the locale according to the environment. On ANSI C-based systems, this is done by calling the setlocale (LC_ALL, "language") function. If an error is encountered, a warning message is issued with the XtWarning() function.
Calls the XSupportsLocale() function to verify that the current locale is supported. If the locale is not supported, a warning message is issued with the XtWarning() function and the locale is set to "C".
Calls the XSetLocaleModifiers() function specifying the empty string.
Returns the value of the current locale. On ANSI C-based systems, this is the return value from a final call to the setlocale (LC_CTYPE, NULL) function.

A client can use this mechanism to establish a locale by calling the XtSetLanguageProc() function prior to the XtDisplayInitialize() function, as in the following example.

Widget top; 
XtSetLanguageProc(NULL, NULL, NULL);  
top = XtAppInitialize( ... ); 
...

XtDisplayInitialize

The XtDisplayInitialize() function first determines the language string to be used for the specified display and loads the application's resource database for this display-host-application combination from the following sources in order of precedence:

Application command line (argv)
Per-host user environment resource file on the local host
Resource property on the server or user-preference resource file on the local host
Application-specific user resource file on the local host
Application-specific class resource file on the local host

The XtDisplayInitialize() function creates a unique resource database for each display parameter specified. When a database is created, a language string is determined for the display parameter in a manner equivalent to the following sequence of actions.

The XtDisplayInitialize() function initially creates two temporary databases. The first database is constructed by parsing the command line. The second database is constructed from the string returned by the XResourceManagerString() function or, if the XResourceManagerString() function returns a null value, the contents of a resource file in the user's home directory. The name for this user-preference resource file is $HOME/.Xdefaults.

The database constructed from the command line is then queried for the resource name.xnlLanguage, class class.XnlLanguage, where name and class are the specified application name and application class. If this database query is unsuccessful, the server resource database is queried; if this query is also unsuccessful, the language is determined from the environment. This is done by retrieving the value of the LANG environment variable. If no language string is found, the empty string is used.

The application-specific class resource file name is constructed from the class name of the application. It points to a localized resource file that is usually installed by the site manager when the application is installed. The file is found by calling the XtResolvePathname() function with the parameters (displayID, applicationdefaults, NULL, NULL, NULL, NULL, 0, NULL). This file should be provided by the developer of the application because it may be required for the application to function properly. A simple application that needs a minimal set of resources in the absence of its class resource file can declare fallback resource specifications with the XtAppSetFallbackResources() function.

The application-specific user resource file name points to a user-specific resource file and is constructed from the class name of the application. This file is owned by the application and typically stores user customizations. Its name is found by calling the XtResolvePathname() function with the parameters (displayID, NULL, NULL, NULL, path, NULL, 0, NULL), where path is defined in an operating-system-specific manner. The path variable is defined to be the value of the XUSERFILESEARCHPATH environment variable if this is defined. Otherwise, the default is vendor-defined.

If the resulting resource file exists, it is merged into the resource database. This file can be provided with the application or created by the user.

The temporary database created from the server resource property or user resource file during language determination is then merged into the resource database. The server resource file is created entirely by the user and contains both display-independent and display-specific user preferences.

If one exists, a user's environment resource file is then loaded and merged into the resource database. This file name is user- and host-specific. The user's environment resource file name is constructed from the value of the user's XENVIRONMENT environment variable for the full path of the file. If this environment variable does not exist, the XtDisplayInitialize() function searches the user's home directory for the .Xdefaults-host file, where host is the name of the machine on which the application is running. If the resulting resource file exists, it is merged into the resource database. The environment resource file is expected to contain process-specific resource specifications that are to supplement those user-preference specifications in the server resource file.