Xt Locale Management (Common Desktop Environment: Internationalization Programmer's Guide)

Common Desktop Environment: Internationalization Programmer's Guide

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.