JIS X0212-1990
1. UID file path name 2. $UIDPATH
characters at the $HOME/ja_JP directory, or placeuil_sample.uidto a unique directory and set theUIDPATHenvironment variable to the full path name of the uil_sample.uidfile. The following list specifies the possible variables:
%U Specifies the UID file string.
%N Specifies the class name of the application.
%L Specifies the value of the xnlLanguage resource
orLC_CTYPEcategory.
%l Specifies the language component of the
xnlLanguage resource or the LC_CTYPE category.
If theXAPPLRESDIRenvironment variable is set, theMrmOpenHierarchy( ) function searches the UID file in the following order:
1. UID file path name
14./usr/lib/X11/uid/%N/%U 15./usr/lib/X11/%L/uid/%U 16./usr/lib/X11/%l/uid/%U 17./usr/lib/X11/uid/%U 18./usr/include/X11/uid/%U
If theXAPPLRESDIRenvironment variable is not set, theMrmOpenHierarchy( ) function uses$HOMEinstead of theXAPPLRESDIRenvironment variable.
default_charset Character Set in UIL
With the default_charset string literal, any characters can be set as a valid string literal. For example, if theLANGenvironment variable isel_GR, the string literal with default_charset can contain any Greek character. If theLANGenvironment variable isja_JP, the default_charset string literal can contain any Japanese character encoded in JapaneseEUC.
If no character set is set to a string literal, the character set of the string literal is set as cur_charset. And, in the system environment, the cur_charset value is always set as default_charset.
Example: uil_sample
Figure 4–4 shows a UIL sample program on English and Japanese environments.
Figure 4–4 Sample UIL program on English and Japanese environments
In the following sample program, LLL indicates locale text, which can be Japanese, Korean, Traditional Chinese, Greek, French, or others.
uil_sample.uil
!
! sample uil file - uil_sample.uil
!
! C source file - uil_sample.c
!
! Resource file - uil-sample.resource
!
module Test
version = ’v1.0’
names = case_sensitive objects = {
XmPushButton = gadget;
}
!************************************
! declare callback procedure
!************************************
procedure exit_CB ;
!***************************************************************
! declare BulletinBoard as parent of PushButton and Text
!***************************************************************
object
bb : XmBulletinBoard { arguments{
XmNwidth = 500;
XmNheight = 200;
};
controls{
XmPushButton pb1;
XmText text1;
};
};
!****************************
! declare PushButton
!****************************
object
pb1 : XmPushButton { arguments{
XmNlabelString = #Normal ‘‘LLLexit buttonLLL’’;
XmNx = 50;
XmNy = 50;
};
callbacks{
XmNactivateCallback = procedure exit_CB;
};
};
!*********************
! declare Text
!*********************
text1 : XmText { arguments{
XmNx = 50;
XmNy = 150;
};
};
end module;
/*
* C source file - uil_sample.c
*
*/
#include <Mrm/MrmAppl.h>
#include <locale.h>
void exit_CB();
static MrmHierarchy hierarchy;
static MrmType *class;
/******************************************/
/* specify the UID hierarchy list */
/******************************************/
static char *aray_file[]=
{‘‘uil_sample.uid’’
};
static int num_file = (sizeof aray_file / sizeof aray_file[0]);
/******************************************************/
/* define the mapping between UIL procedure names */
/* and their addresses */
/******************************************************/
static MRMRegisterArg reglist[]={
{‘‘exit_CB’’,(caddr_t) exit_CB}
Compound Strings in UIL
Three mechanisms exist for specifying strings in UIL files:
4 As string literals, which may be stored in UID files as either null-terminated strings or compound strings
4 As compound strings
4 As wide character strings
Both string literals and compound strings consist of text, a character set, and a writing direction. For string literals and for compound strings with no explicit direction, UIL infers the writing direction from the character set. The UIL
concatenation operator (&) concatenates both string literals and compound strings.
Regardless of whether UIL stores string literals in UID files as null-terminated strings or as compound strings, it stores information about each string’s character set and writing direction along with the text. In general, UIL stores string literals or string expressions as compound strings in UID files under the following conditions:
4 When a string expression consists of two or more literals with different character sets or writing directions
4 When the literal or expression is used as a value that has a compound string data type (such as the value of a resource whose data type is compound string)
UIL recognizes a number of keywords specifying character sets. UIL associates parsing rules, including parsing direction and whether characters have 8 or 16 bits, for each character set it recognizes. It is also possible to define a character set using the UILCHARACTER_SETfunction.
The syntax of a string literal is one of the following:
4 ’[character_string]’
4 [#char_set]
4 “[character_string]”
For each syntax, the character set of the string is determined as follows:
4 For a string declared as ’character_string’, the character set is the code set component of theLANGenvironment variable, if it is set in the UIL compilation environment; or it is the value ofXmFALLBACK_CHARSETif theLANGenvironment variable is not set or has no code set. By default, the value of
XmFALLBACK_CHARSETis ISO8859-1, but vendors may supply different values.
4 For a string declared as #char_set “string”, the character set is char_set.
4 For a string declared as “character_string”, the character set depends on whether the module has aCHARACTER_SETclause and whether the UIL compiler’s use_setlocale_flagis set.
4 If the module has aCHARACTER_SETclause, the character set is the one specified in that clause.
4 If the module has noCHARACTER_SETclause but theuilcommand was started with the-soption, or if theUil( )function was started with
use_setlocale_flag set, UIL calls thesetlocale( )function and parses the string in the current locale. The character set of the resulting string is XmFONTLIST_DEFAULT_TAG.
4 If the module has noCHARACTER_SETclause and the uil command was started without the-soption, or if theUil( )function was started without use_setlocale_flag, the character set is the code set component of the LANG environment variable, if it is set in the UIL compilation environment, or the character set is the value ofXmFALLBACK_CHARSETifLANGis not set or has no code set.
UIL always stores a string specified using theCOMPOUND_STRINGfunction as a compound string. This function takes as arguments a string expression and optional specifications of a character set, direction, and whether to append a separator to the string. If no character set or direction is specified, UIL derives it from the string expression, as described in the preceding section.
Note -Certain predefined escape sequences, beginning with a \ (backslash), may be displayed in string literals, with the following exceptions:
4 A string in single quotation marks can span multiple lines, with each new line character escaped by a backslash. A string in double quotation marks cannot span multiple lines.
4 Escape sequences are processed literally inside a string that is parsed in the current locale (a localized string).
CHAPTER
5
Xt and Xlib Dependencies
This chapter discusses tasks related to internationalizing with Xt and Xlib.
4 “Locale Management” on page 105
4 “Font Management” on page 112
4 “Drawing Localized Text” on page 114
4 “Inputting Localized Text” on page 114
4 “Interclient Communications Conventions for Localized Text” on page 123
4 “Messages” on page 126
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 thesetlocale( )function. This function configures the locale operation of both the host C library and Xlib. The operation of Xlib is governed by theLC_CTYPEcategory; this is called the current locale.
TheXSupportsLocale( )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( ), andXSetLocaleModifiers( ). 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.
TheXSetLocaleModifiers( )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:
1. A command-line option 2. A resource
3. 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
TABLE 5–1 Locale and Modifier Dependencies (continued) Locale from... Affects the Function... In the...
Resources
setlocale XrmGetFileDatabase XrmGetStringDatabase
Locale of XrmDatabase
XrmDatabase XrmPutFileDatabase XrmLocaleOfDatabase
Locale of XrmDatabase
Setting Standard Properties
setlocale XmbSetWMProperties Encoding of supplied returned text (someWM_ propertytext 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
TABLE 5–1 Locale and Modifier Dependencies (continued) Locale from... Affects the Function... In the...
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 theXSetLocaleModifiers( ) 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 themblen( ),mbtowc( ), wctomb( ), andstrtok( )ANSI C functions.
Xt Locale Management
Xt locale management includes the following two functions:
4 XtSetLanguageProc( )
4 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 theXtAppInitialize( )function). Therefore, thesetlocale( )function may be needed after theXtSetLanguageProc( )function and the initializing of the toolkit (for example, if calling thecatopen( )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 theXtSetLanguageProc( )function.
The language procedure allows an application to set the locale to the value of the language resource determined by theXtDisplayInitialize( )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 theXtDisplayInitialize( )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.
TheXtSetLanguageProc( ) function sets the language procedure that is called from theXtDisplayInitialize( )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:
4 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 theXtWarning( )function.
4 Calls theXSupportsLocale( )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".
4 Calls theXSetLocaleModifiers( )function specifying the empty string.
4 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 theXtDisplayInitialize( )function, as in the following example.
Widget top;
XtSetLanguageProc(NULL, NULL, NULL);
top = XtAppInitialize( ... );
...
XtDisplayInitialize
TheXtDisplayInitialize( )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:
1. Application command line (argv)
2. Per-host user environment resource file on the local host
3. Resource property on the server or user-preference resource file on the local host 4. Application-specific user resource file on the local host
5. Application-specific class resource file on the local host
TheXtDisplayInitialize( )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.
TheXtDisplayInitialize( )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 theXResourceManagerString( ) function or, if theXResourceManagerString( )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.
Font Management
International text drawing is done using a set of one or more fonts, as needed for the locale of the text.
The two methods of internationalized drawing within the system environment allow clients to choose one of the static output widgets (for example,XmLabel) or to choose theDrawingAreawidget to draw with any other primitive function.
Static output widgets require that text be converted toXmString.
The following information explains the mechanism for managing fonts using the Xlib routines and functions.
Creating and Freeing a Font Set
Xlib international text drawing is done using a set of one or more fonts, as needed for the locale of the text. Fonts are loaded according to a list of base font names supplied by the client and the charsets required by the locale. The XFontSet is an opaque type.
4 TheXCreateFontSet( )function is used to create an international text drawing font set.
4 TheXFontsOfFontSet( )function is used to obtain a list of XFontStruct structures and full font names given an XFontSet.
4 To obtain the base font name list and the selected font name list given an XFontSet, use theXBaseFontNameListOfFontSet( )function.
4 To obtain the locale name given an XFontSet, use theXLocaleOfFontSet( ) function.
4 TheXLocaleOfFontSet( )function returns the name of the locale bound to the specified XFontSet as a null-terminated string.
4 TheXFreeFontSet( )function frees the specified font set. The associated base font name list, font name list, XFontStruct list, and XFontSetExtents, if any, are freed.
Obtaining Font Set Metrics
Metrics for the internationalized text drawing functions are defined in terms of a primary draw direction, which is the default direction in which the character origin advances for each succeeding character in the string. The Xlib interface is currently defined to support only a left-to-right primary draw direction. The drawing origin is the position passed to the drawing function when the text is drawn. The baseline is a line drawn through the drawing origin parallel to the primary draw direction.
Character ink is the pixels painted in the foreground color and does not include interline or intercharacter spacing or image text background pixels.
The drawing functions are allowed to implement implicit text direction control, reversing the order in which characters are rendered along the primary draw direction in response to locale-specific lexical analysis of the string.
Regardless of the character rendering order, the origins of all characters are on the primary draw direction side of the drawing origin. The screen location of a particular character image may be determined with theXmbTextPerCharExtents( )or XwcTextPerCharExtents( )functions.
The drawing functions are allowed to implement context-dependent rendering, where the glyphs drawn for a string are not simply a combination of the glyphs that represent each individual character. A string of two characters drawn with the XmbDrawString( )function may render differently than if the two characters were drawn with separate calls to theXmbDrawString( ) function. If the client adds or inserts a character in a previously drawn string, the client may need to redraw some adjacent characters to obtain proper rendering.
The drawing functions do not interpret newline characters, tabs, or other control characters. The behavior when nonprinting characters are drawn (other than spaces) is implementation-dependent. It is the client’s responsibility to interpret control characters in a text stream.
To find out about context-dependent rendering, use the
XContextDependentDrawing( )function. TheXExtentsOfFontSet( )function obtains the maximum extents structure given an XFontSet. The
XmbTextEscapement( )andXwcTextEscapement( ) functions obtain the escapement in pixels of the specified text as a value. TheXmbTextExtents( )and XwcTextExtents( )functions obtain the overall bounding box of the string’s image and a logical bounding box (overall_ink_return and overall_logical_return arguments respectively). TheXmbTextPerCharExtents( )andXwcTextPerCharExtents( ) functions return the text dimensions of each character of the specified text, using the fonts loaded for the specified font set.