















        Chapter 11.  IInntteerrnnaattiioonnaalliizzaattiioonn








             Internationalization is a method of application
             development that allows the application to be run in
             many different languages without having to be rewritten
             or recompiled.  This chapter describes how to design
             applications to use Motif's internationalization
             capability.  It is not a general discussion of
             internationalization.



        11.1  IIssssuueess iinn IInntteerrnnaattiioonnaalliizzeedd AApppplliiccaattiioonnss


             There are several important issues to keep in mind when
             designing an application so that it takes advantage of
             Motif's internationalization capabilities.



        11.1.1  IInntteerrnnaattiioonnaalliizzaattiioonn aanndd LLooccaalliizzaattiioonn


             An internationalized application contains no code that
             is dependent on the user's language, the characters
             needed to represent that language, or any formats (such
             as date and currency) that the user expects to see and
             interact with.  Motif accomplishes this by storing
             language and custom dependent information outside the
             application.






        August 26, 1994                                         11-1







        OSF/Motif Programmer's Guide


             The following figure shows the kinds of information
             that should be external to an application to simplify
             internationalization.

             FFiigguurree 1111--11..  Information External to the Application

             Because the language and culture dependent information
             is separate from the application source code, the
             application does not need to be rewritten or recompiled
             to be marketed in a different countries.  Instead, the
             only requirement is for the external information to be
             llooccaalliizzeedd to accommodate local language and custom.

             Localizing the application includes the process of
             translating certain parts of the external information
             into the appropriate language and storing the
             translated information in files that are then accessed
             by the application.  In addition, the application may
             be told the format to use to display time, date, and
             the other language or culture dependent formats shown
             in the previous figure.

             Every language consists of a set of characters that,
             either individually or in combination, represents
             meaningful words or concepts in the language.  The set
             of characters is called a cchhaarraacctteerr sseett.  The set of
             binary values needed to represent all the characters in
             a language is called a coded character set or, more
             simply, a ccooddee sseett.

             Several attempts were started long ago to standardize
             character sets and continue to this day.  The most
             commonly used code set for English is the American
             National Standard Code for Information Interchange
             (ASCII).  It originally used a 7-bit encoding scheme
             plus an eighth bit for error control.  Using 7 bits for
             character representation allows 128 unique binary
             values.  Later versions use the eighth bit as a code
             bit allowing 255 characters.  Both are fine for English
             and some other alphabetic languages, but neither is
             suitable for ideographic languages such as Chinese,
             Japanese, and Korean.  Ideographic languages represent
             a concept or an idea as a single character;
             consequently, there are thousands of characters in
             these languages, and two or more bytes are needed to
             represent the characters.

             Other standard code sets have been developed to
             accommodate other languages.  The ISO8859 standard is
             perhaps the most commonly used of these.  Different
             versions of the ISO8859 standard exist for various




        11-2                                         August 26, 1994







                                                Internationalization


             areas of the world.  The following table shows a
             typical language and character set relationship for
             various areas.
               TTAABBLLEE 1111--11..  Areas and Typical Character Sets

                      AArreeaa oorr LLaanngguuaaggee    CChhaarraacctteerr SSeett
                      ____________________________________
                      English             ASCII, ISO8859-1
                      Western Europe      ISO8859-1
                      Eastern Europe      ISO8859-2
                      Northern Europe     ISO8859-3
                      Russia (Cyrillic)   ISO8859-5
                      Hebrew              ISO8859-6
                      Greek               ISO8859-7, 8, 9
                      Japan               Shift JIS
                      Japan               UJIS

             See the specifications for the American National
             Standards Institute (ANSI) C programming language and
             the _X/_O_p_e_n _P_o_r_t_a_b_i_l_i_t_y _G_u_i_d_e, _I_s_s_u_e _3 (XPG3) for more
             information on standards involved in
             internationalization.



        11.1.2  OObbttaaiinniinngg IInnppuutt


             Special considerations must be made for the user of an
             application to input characters in the local written
             language.  Virtually all applications require some
             action on the part of the user, often asking for input
             in one form or another.  For example, an application
             can ask the user to input information in text form,
             such as name, home address, and so on.  The user must
             then enter this information by typing it on the
             keyboard in the normal manner.  This is done with
             relative ease in an English-based application but can
             become more complex when other language text is
             desired.

             Motif uses Xlib functions to provide the basic support
             for obtaining input in a Text widget.












        August 26, 1994                                         11-3







        OSF/Motif Programmer's Guide


        11.1.2.1  TThhee PPrroobblleemmss


             Many languages are expressed by means of an alphabet
             made up of characters or letters.  The letters are
             arranged in groups to form meaningful words.  A
             keyboard suitable for the language normally contains
             all the letters of the alphabet, plus the standard
             numerals and punctuation marks.  The problem arises
             when the keyboard does _n_o_t have all the alphabet
             characters.  This can happen when a German user is
             using an English-based keyboard and needs a German
             character such as ",B."

             A far more involved example is the case of defining a
             keyboard to use for the ideographic languages.  Because
             thousands of characters are needed to represent an
             ideographic language, no reasonable keyboard can be
             constructed with a single key for each character.



        11.1.2.2  TThhee SSoolluuttiioonn


             Motif solves these input problems by using an iinnppuutt
             mmeetthhoodd, which is a layer of mapping between the
             keyboard keys (or combinations of keys) that the user
             types and the text data that is passed to the
             application.  For example, the Swedish user with an
             English keyboard who needs the letter "O/" must enter a
             _c_o_m_b_i_n_a_t_i_o_n of keystrokes (this varies among vendors
             but could be <<EExxtteenndd cchhaarr>> <<OO>> <<//>> as an example)
             rather than just one keystroke.  This is very similar
             to the act of using the <<SShhiifftt>> key to access uppercase
             letters.

             An ideographic language's input method is often based
             on the language's phonetics, but there are also input
             methods based on a common graphics property of certain
             characters.  The graphics method involves defining a
             key to map to a common graphic symbol that is the basis
             for multiple characters.  The phonetic method is more
             commonly used.  It requires a phonetic (alphabet-based)
             writing system.  The number of phonetic signs or
             characters is few enough that a unique key is assigned
             to each phoneme. Characters are entered by pressing the
             appropriate phonetic keys.  In several popular input
             methods, the user types a phonetic representation of a
             spoken word and the input method determines which
             characters are pronounced that way.  If only one




        11-4                                         August 26, 1994







                                                Internationalization


             character meets this criterion, it is displayed.  If
             more than one character meets the criterion, a list of
             all characters found is displayed and the user chooses
             the desired one.  It is then passed to the application.
             See Section 11.4.1 for more information on input
             methods.



        11.1.3  DDiissppllaayyiinngg OOuuttppuutt


             Displaying the output produced by an application
             intended for international use also requires some
             consideration.  To display text, it must have the
             appropriate content, encoding and fonts.  For example,
             many languages, especially ideographic ones, require
             more than one font.  Bitmaps and pixmaps must be
             localized as well.  An icon that is an appropriate or
             meaningful symbol in one country may be totally
             inappropriate or meaningless in another.



        11.1.4  LLooccaalleess aanndd LLooccaalliizzaattiioonn


             A locale is the language environment determined by the
             application at run time.  XPG3 defines locale as a
             means of specifying three characteristics of a language
             environment that may be needed for localization:
             language, territory, and code set.  Motif supports only
             one locale per application; that is, an application can
             set the locale only once, at start-up time.

             Motif uses the locale to help find:

                +o Resource files

                +o UID files

                +o Bitmap files

                +o Fonts used to display text and labels

                +o Text input method

             The ANSI C method of setting the locale in an
             application is to use the function sseettllooccaallee.  How
             sseettllooccaallee obtains a language when the language is not
             explicitly referenced in the call to sseettllooccaallee is




        August 26, 1994                                         11-5







        OSF/Motif Programmer's Guide


             system dependent.  For example, on POSIX systems, the
             environment variable LLAANNGG is used.  The locale name is
             also used to establish a path to the localized files of
             information.  How this is actually accomplished is
             explained in Section 11.3.



        11.2  CCoommppoouunndd SSttrriinnggss,, FFoonnttss,, aanndd TTeexxtt DDiissppllaayy


             A ccoommppoouunndd ssttrriinngg is a means of encoding text so that
             it can be displayed in many different languages or
             fonts without changing anything in the program. Motif
             uses compound strings to display all text except that
             in the Text and TextField widgets.  This section
             describes the structure of a compound string and the
             interaction between a compound string and a font list
             that determines how the compound string is displayed.



        11.2.1  CCoommppoouunndd SSttrriinngg CCoommppoonneennttss


             A compound string is a byte stream in ASN.1 encoding,
             consisting of tag-length-value segments.  Semantically,
             a compound string has components that contain the text
             to be displayed, a tag (called a font list element tag)
             that will be matched with an element of a font list,
             and an indicator denoting the direction in which it is
             to be displayed.

             A compound string component can be one of four types:

                +o A font list element tag.

                     - The font list element tag
                       XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG indicates that the
                       text is encoded in the codeset of the current
                       locale.

                     - Other font list element tags are used later
                       to match text with particular entries in a
                       font list.

                +o A direction identifier.

                +o The text of the string.  For internationalized
                  applications, the text falls into two broad
                  categories: either the text requires localized




        11-6                                         August 26, 1994







                                                Internationalization


                  treatment or it does not.

                +o A separator.

             The following section describes each of the compound
             string components:

             Font list element tag
                       The font list element tag is a string value
                       that correlates the text component of a
                       compound string to a font or a font set in a
                       font list.

             Direction The relationship between the order in which
                       characters are entered on the keyboard and
                       the order in which the characters are
                       displayed on the screen.  For example, the
                       display order is left to right in English,
                       French, German, and Italian and right to left
                       in Hebrew and Arabic.

             Text      The text to be displayed.

             Separator A separator is a special form of a compound
                       string component that has no value.  It is
                       used to separate other segments.

             Motif uses the specified font list element tag
             identified in the text component to display the
             compound string.  A specified font list element tag is
             used until a new font list element tag is encountered.
             Motif provides a special font list element tag,
             XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG, that matches a font that is
             correct for the current codeset.  It identifies the
             default entry in a font list.  See Section 11.2.3 for
             more information.

             The direction segment of a compound string specifies
             the direction in which the text is displayed.
             Direction can be left-to-right or right-to-left.



        11.2.1.1  CCoommppoouunndd SSttrriinnggss aanndd RReessoouurrcceess


             Compound strings are used to display all text except
             that in the Text and TextField widgets.  The compound
             string is set into the appropriate widget resource so
             that it can be displayed.  For example, the label for
             the PushButton widget is inherited from the Label




        August 26, 1994                                         11-7







        OSF/Motif Programmer's Guide


             widget, and the resource is XXmmNNllaabbeellSSttrriinngg, which is
             type XXmmSSttrriinngg.  This means that the resource expects a
             value that is a compound string.  A compound string can
             be created programmatically or defined in a resource
             file.



        11.2.1.1.1  SSeettttiinngg aa CCoommppoouunndd SSttrriinngg PPrrooggrraammmmaattiiccaallllyy

             An application can set this resource programmatically
             by creating the compound string using one of the
             compound string convenience functions.  There are
             several such functions:

             XXmmSSttrriinnggCCrreeaattee
                       This function creates a compound string with
                       text and a font list element tag, both of
                       which are arguments in the function call.

             XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd
                       This function creates a compound string in
                       the encoding of the current locale and
                       automatically sets the font list entry tag to
                       XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

             The following code segment shows one way to set
             XXmmNNllaabbeellSSttrriinngg for a PushButton programmatically:

             Widget    button;
             Args      args[10];
             int       n;
             XmString  button_label;
                     .
                     .
             button_label = XmStringCreateLocalized (locvar,
                              XmFONTLIST_DEFAULT_TAG);
             /* locvar is a variable assumed to contain
              * locale-encoded text.
              * Create an argument list for the button */
             n = 0;
             XtSetArg (args[n], XmNlabelString, button_label); n++;

             /* Create and manage the button */
             button = XmCreatePushButton (toplevel, "button", args, n);
             XtManageChild (button);
             XmStringFree (button_label);








        11-8                                         August 26, 1994







                                                Internationalization


        11.2.1.1.2  SSeettttiinngg aa CCoommppoouunndd SSttrriinngg iinn aa DDeeffaauullttss FFiillee

             In an internationalized program, the label string for
             the button label should be obtained from an external
             source.  For example, the button label can come from a
             resource file instead of the program.  For this
             example, assume that the PushButton is a child of a
             Form widget called "form1".

             *form1.button.labelString:  Push Here

             Here, Motif's string-to-compound-string converter
             produces a compound string from the resource file text.
             This converter always uses XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.



        11.2.1.2  CCoommppoouunndd SSttrriinnggss iinn UUIILL



             Three basic mechanisms exist for specifying strings in
             UIL files:

                +o String literals, which may be stored in UID files
                  as either NULL-terminated strings or compound
                  strings

                +o Compound strings

                +o 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.

             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:

                +o When a string expression consists of two or more
                  literals with different character sets or writing
                  directions




        August 26, 1994                                         11-9







        OSF/Motif Programmer's Guide


                +o 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
             UIL cchhaarraacctteerr__sseett function.

             The syntax of a string literal is one of the following:

                  ''[_c_h_a_r_a_c_t_e_r__s_t_r_i_n_g]''
                  [##_c_h_a_r__s_e_t]""[_c_h_a_r_a_c_t_e_r__s_t_r_i_n_g]""

             For each syntax, the character set of the string is
             determined as follows:

                +o For a string declared as ''_s_t_r_i_n_g'', the character
                  set is the codeset component of the LLAANNGG
                  environment variable if it is set in the UIL
                  compilation environment, or the value of
                  XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT if LLAANNGG is not set or has no
                  codeset.  By default, the value of
                  XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT is ISO8859-1, but vendors may
                  supply different values.

                +o For a string declared as ##_c_h_a_r__s_e_t""_s_t_r_i_n_g"", the
                  character set is _c_h_a_r__s_e_t.

                +o For a string declared as ""_s_t_r_i_n_g"", the character
                  set depends on whether or not the module has a
                  cchhaarraacctteerr__sseett clause and on whether or not the UIL
                  compiler's uussee__sseettllooccaallee__ffllaagg is set:

                     - If the module has a cchhaarraacctteerr__sseett clause, the
                       character set is the one specified in that
                       clause.

                     - If the module has no cchhaarraacctteerr__sseett clause but
                       the uuiill command was invoked with the --ss
                       option or the UUiill function was invoked with
                       the uussee__sseettllooccaallee__ffllaagg set, UIL calls
                       sseettllooccaallee and parses the string in the
                       current locale.  The character set of the
                       resulting string is XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

                     - If the module has no cchhaarraacctteerr__sseett clause and
                       the uuiill command was invoked without the --ss




        11-10                                        August 26, 1994







                                                Internationalization


                       option or the UUiill function was invoked
                       without the uussee__sseettllooccaallee__ffllaagg, the character
                       set is the codeset component of the LLAANNGG
                       environment variable if it is set in the UIL
                       compilation environment; if LLAANNGG is not set
                       or has no codeset, the character set is the
                       value of XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT.

             UIL always stores a string specified using the
             ccoommppoouunndd__ssttrriinngg function as a compound string.  This
             function takes as arguments a string expression and
             optional specifications of a character set, direction,
             and whether or not to append a separator to the string.
             If no character set or direction is specified, UIL
             derives it from the string expression, as described
             above.

             Note that certain predefined escape sequences,
             beginning with a backslash, may appear in string
             literals, with these exceptions:

                +o A string in single quotes can span multiple lines,
                  with each newline escaped by a backslash.  A
                  string in double quotes cannot span multiple
                  lines.

                +o Escape sequences are processed literally inside a
                  string that is parsed in the current locale (a
                  localized string).

             For more information on UIL string and compound string
             syntax, see the UUIILL((55XX)) reference page in the _O_S_F/_M_o_t_i_f
             _P_r_o_g_r_a_m_m_e_r'_s _R_e_f_e_r_e_n_c_e.



        11.2.2  FFoonnttss,, FFoonntt LLiissttss,, aanndd FFoonntt SSeettss


             Motif uses font sets and font lists to display text. A
             font defines set of glyphs that represent the
             characters in a given language.  A font set is a group
             of fonts that are needed to display text for a given
             locale.  A font list is a list of fonts, font sets, or
             a combination of the two, that may be used.  Motif has
             convenience functions to create a font list.









        August 26, 1994                                        11-11







        OSF/Motif Programmer's Guide


        11.2.2.1  FFoonntt LLiisstt SSttrruuccttuurree


             Motif requires a font list for text display.  A font
             list is a list of font structures, font sets, or both,
             each of which has a tag to identify it.  A font set
             ensures that all characters in the current language can
             be displayed.  With font structures, the responsibility
             for ensuring that all characters can be displayed rests
             with the programmer.

             Each entry in a font list is in the form of a {tag,
             element} pair, where _e_l_e_m_e_n_t can be either a single
             font or a font set.  The application can create a font
             list entry from either a single font or a font set.
             For example, the following code segment creates a font
             list entry for a font set:

             char font1[] =
                "-adobe-courier-medium-r-normal--10-100-75-75-M-60";
             XmFontListEntry font_list_entry;
             font_list_entry = XmFontListEntryLoad (display,
                                  font1, XmFONT_IS_FONT, "font_tag");

             XXmmFFoonnttLLiissttEEnnttrryyLLooaadd loads a font or creates and loads a
             font set.  There are four arguments to the function:

             _d_i_s_p_l_a_y   The display on which the font list is to be
                       used

             _f_o_n_t__n_a_m_e A string that represents either a font name
                       or a base font name list, depending on the
                       _t_y_p_e argument

             _t_y_p_e      A value that specifies whether _f_o_n_t__n_a_m_e
                       refers to a font name or a base font name
                       list

             _t_a_g       A string that represents the tag for this
                       font list entry

             If _t_y_p_e is XXmmFFOONNTT__IISS__FFOONNTTSSEETT, XXmmFFoonnttLLiissttEEnnttrryyLLooaadd
             creates a font set in the current locale from the value
             in _f_o_n_t__n_a_m_e.  The character set(s) of the fonts
             specified in the font set are dependent on the locale.
             If _t_y_p_e is XXmmFFOONNTT__IISS__FFOONNTT, XXmmFFoonnttLLiissttEEnnttrryyLLooaadd opens
             the font found in _f_o_n_t__n_a_m_e.  In either case, the font
             or font set is placed into a font list entry.

             Now, the following code creates a font list, using the
             font list entry just created:




        11-12                                        August 26, 1994







                                                Internationalization


             XmFontList font_list;
             XmFontListEntry font_list_entry;
                .
                .
             font_list = XmFontListAppendEntry (NULL, font_list_entry);
             XmFontListEntryFree (font_list_entry);

             The code example above creates a new font list and
             appends the entry _f_o_n_t__l_i_s_t__e_n_t_r_y to it.

             Once a font list has been created,
             XXmmFFoonnttLLiissttEEnnttrryyAAppppeenndd adds a new entry to it.  The
             following example uses XXmmFFoonnttLLiissttEEnnttrryyCCrreeaattee to create
             a new font list entry for an existing font list:

             XFontSet font2;
             char *font_tag;
             XmFontListEntry font_list_entry2;
                .
                .
             font_list_entry2 = XmFontListEntryCreate (font_tag,
                                   XmFONT_IS_FONT_SET,
                                   (XtPointer) font2);

             _f_o_n_t_2 specifies an XXFFoonnttSSeett returned by XXCCrreeaatteeFFoonnttSSeett.
             The arguments to XXmmFFoonnttLLiissttEEnnttrryyCCrreeaattee are _f_o_n_t__t_a_g,
             XXmmFFOONNTT__IISS__FFOONNTTSSEETT, and _f_o_n_t_2, which are the tag, type,
             and font, respectively.  The tag and the font set are
             the {tag, element} pair of the font list entry.

             Now, to add this entry to the font list, use
             XXmmFFoonnttLLiissttAAppppeennddEEnnttrryy again, only this time its first
             parameter specifies the existing font list:

             font_list = XmFontListAppendEntry(font_list, font_list_entry2);
             XmFontListEntryFree(font_list_entry2);



        11.2.2.2  FFoonntt LLiissttss aanndd RReessoouurrcceess


             The syntax for specifying a font list in a resource
             file depends on whether the list contains fonts, font
             sets, or both.

                +o To obtain a font, specify a font and an optional
                  font list element tag.  If the tag is present, it
                  should be preceded by an equal sign (=).  If the
                  tag is not present, do not use the equal sign.
                  Entries specifying more than one font are




        August 26, 1994                                        11-13







        OSF/Motif Programmer's Guide


                  separated by commas.

                +o To obtain a font set, specify a base font list and
                  an optional font list element tag.  The tag should
                  be preceded by a colon (:) instead of an equal
                  sign.  If the tag is not present, the colon _m_u_s_t
                  still be present, because this is what
                  distinguishes a font from a font set in the
                  resource declaration.  Fonts specified in the base
                  font list are separated by semicolons (;).
                  Entries specifying more than one font set are
                  separated by commas.

             If the font list element tag is not present in either
             case, Motif uses the default XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.
             Here are some examples:

                +o Specifying a font:

                     - Using the default font list element tag:

                  *fontList:  fixed
                  *fontList:\
                    -adobe-courier-medium-r-normal--10-100-75-75-M-60-iso8859-1

                     - Specifying a font list element tag:

                       *fontList:  fixed=ROMAN, 8x13bold=BOLD

                     - Specifying two fonts, one with the default
                       font list element tag and one with an
                       explicit tag:

                       *fontList:  fixed, 8x13bold=BOLD

                +o Specifying a font set:

                     - List the fonts explicitly without specifying
                       a font list element tag:

                       *fontList:\
                         -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                         -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120;\
                         -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                         -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150:

                     - Let Xlib select the fonts without specifying
                       a font list element tag:

                       *fontList:  -*-*-*-R-Normal--*-180-100-100-*-*:





        11-14                                        August 26, 1994







                                                Internationalization


                     - List the fonts explicitly and specify a font
                       list element tag as MY_TAG:

                   *fontList:\
                     -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                     -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120;\
                     -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                     -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150:MY_TAG

                     - Let Xlib select the fonts and specify a font
                       list element tag as MY_TAG:

                       *fontList:  -*-*-*-R-Normal--*-180-100-100-*-*:MY_TAG

                     - List the fonts explicitly and specify a font
                       list element tag for bold fonts, but use the
                       default font list element tag for medium
                       fonts:

                    *fontList:\
                      -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                      -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120;\
                      -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                      -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150:,\
                      -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                      -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120;\
                      -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                      -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150:BOLD

                     - Let Xlib select the fonts and specify a font
                       list element tag for bold fonts and use the
                       default font list element tag for the others:

                       *fontList:  -*-*-*-R-Normal--*-180-100-100-*-*:,\
                                   -*-*-Bold-R-Normal--*-180-100-100-*-*:BOLD



        11.2.2.3  FFoonntt LLiisstt RReessoouurrccee DDeeffaauullttss


             A font list resource exists for a number of different
             widgets.  Motif uses a hierarchy system to determine
             the font list it should use.  There are several font
             list resources for VVeennddoorrSShheellll, XXmmBBuulllleettiinnBBooaarrdd, and
             XXmmMMeennuuSShheellll.  These resources can be set, either
             programmatically or in resource files.  VVeennddoorrSShheellll and
             XXmmMMeennuuSShheellll have some common font list resources but
             one of them, XXmmNNddeeffaauullttFFoonnttLLiisstt, exists only for
             compatibility with earlier Motif releases.  The widgets
             that have a font list resource (or resources) are




        August 26, 1994                                        11-15







        OSF/Motif Programmer's Guide


             listed in the following table.  Note that in some cases
             the resource is _n_o_t named XXmmNNffoonnttLLiisstt.

               TTAABBLLEE 1111--22..  Widgets With Font List Resources

                      WWiiddggeett            RReessoouurrccee NNaammee
                      ____________________________________
                      VVeennddoorrSShheellll       XXmmNNbbuuttttoonnFFoonnttLLiisstt
                      VVeennddoorrSShheellll       XXmmNNddeeffaauullttFFoonnttLLiisstt
                      VVeennddoorrSShheellll       XXmmNNllaabbeellFFoonnttLLiisstt
                      VVeennddoorrSShheellll       XXmmNNtteexxttFFoonnttLLiisstt
                      XXmmBBuulllleettiinnBBooaarrdd   XXmmNNbbuuttttoonnFFoonnttLLiisstt
                      XXmmBBuulllleettiinnBBooaarrdd   XXmmNNllaabbeellFFoonnttLLiisstt
                      XXmmBBuulllleettiinnBBooaarrdd   XXmmNNtteexxttFFoonnttLLiisstt
                      XXmmLLaabbeell           XXmmNNffoonnttLLiisstt
                      XXmmLLaabbeellGGaaddggeett     XXmmNNffoonnttLLiisstt
                      XXmmLLiisstt            XXmmNNffoonnttLLiisstt
                      XXmmMMeennuuSShheellll       XXmmNNbbuuttttoonnFFoonnttLLiisstt
                      XXmmMMeennuuSShheellll       XXmmNNddeeffaauullttFFoonnttLLiisstt
                      XXmmMMeennuuSShheellll       XXmmNNllaabbeellFFoonnttLLiisstt
                      XXmmSSccaallee           XXmmNNffoonnttLLiisstt
                      XXmmTTeexxtt            XXmmNNffoonnttLLiisstt
                      XXmmTTeexxttFFiieelldd       XXmmNNffoonnttLLiisstt

             The three resources XXmmNNbbuuttttoonnFFoonnttLLiisstt,
             XXmmNNllaabbeellFFoonnttLLiisstt, and XXmmNNtteexxttFFoonnttLLiisstt are used to
             specify a font list for descendants of a type
             associated with the resource.  For example,
             XXmmNNbbuuttttoonnFFoonnttLLiisstt specifies the font list used for
             button descendants of VVeennddoorrSShheellll, XXmmBBuulllleettiinnBBooaarrdd, and
             XXmmMMeennuuSShheellll.  If a button's XXmmNNffoonnttLLiisstt is NULL at
             initialization, the font list for the button is set by
             searching the parent hierarchy of the button widget or
             gadget for an ancestor that is a subclass of
             VVeennddoorrSShheellll, XXmmBBuulllleettiinnBBooaarrdd, or XXmmMMeennuuSShheellll.  If such
             an ancestor is found, the button's font list is set to
             the value of XXmmNNbbuuttttoonnFFoonnttLLiisstt in the ancestor widget.
             If no such ancestor is found, the result is
             implementation dependent.



        11.2.2.4  FFoonntt LLiissttss iinn UUIILL



             UIL has three functions for use in creating font lists:
             ffoonntt, ffoonnttsseett, and ffoonntt__ttaabbllee.  The ffoonntt and ffoonnttsseett
             functions create font list entries.  The ffoonntt__ttaabbllee
             function creates a font list from these font list
             entries.




        11-16                                        August 26, 1994







                                                Internationalization


             The ffoonntt function creates a font list entry containing
             a font specification.  The argument is a string
             representing an XLFD font name.  The ffoonnttsseett function
             creates a font list entry containing a font set
             specification.  The argument is a comma-separated list
             of XLFD font names representing a base name font list.

             Both ffoonntt and ffoonnttsseett have optional cchhaarraacctteerr__sseett
             parameters that specify the font list element tag for
             the font list entry.  In both cases, if no
             cchhaarraacctteerr__sseett parameter is specified, UIL determines
             the font list element tag as follows:

                +o If the module contains no cchhaarraacctteerr__sseett
                  declaration and if the uuiill command was invoked
                  with the --ss option or the UUiill function was invoked
                  with the uussee__sseettllooccaallee__ffllaagg set, the font list
                  element tag is XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

                +o Otherwise, the font list element tag is the
                  codeset component of the LLAANNGG environment variable
                  if it is set in the UIL compilation environment,
                  or the value of XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT if LLAANNGG is not
                  set or has no codeset.

             The ffoonntt__ttaabbllee function creates a font list from a
             comma-separated list of font list entries, created by
             FFOONNTT or FFOONNTTSSEETT.  The resulting font list can be used
             as the value of a font list resource.  If a single font
             list entry is supplied as the value for such a
             resource, UIL converts the entry to a font list.



        11.2.3  CCoommppoouunndd SSttrriinnggss aanndd FFoonntt LLiissttss


             When Motif displays a compound string, it associates
             each segment with a font or font set by means of the
             font list element tag for that segment.  The
             application must have loaded the desired font or font
             set, created a font list that contains that font or
             font set and its associated font list element tag, and
             created the compound string segment with the same tag.

             Motif follows a set search procedure when when it binds
             a compound string to a font list entry:

               1.  Motif searches the font list for an exact match
                   with the font list element tag specified in the
                   compound string.  If it finds a match, the




        August 26, 1994                                        11-17







        OSF/Motif Programmer's Guide


                   compound string is bound to that font list entry.

               2.  If the above does not provide a binding between
                   the compound string and the font list, Motif
                   binds the compound string to the first element in
                   the font list, regardless of its font list
                   element tag.

             For backward compatibility, if an exact match is not
             found, XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG in either a compound
             string or a font list matches the tag that would result
             from creating a compound string or font list entry with
             a tag of XXmmSSTTRRIINNGG__DDEEFFAAUULLTT__CCHHAARRSSEETT.

             The following figure shows the relationships between a
             compound string, a font set, and a font list when the
             font list element tag is set to something other than
             XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

                 FFiigguurree 1111--22..  Compound String and Explicit Tag

             The following example shows how to use a tag called
             _t_a_g_b.

             XFontStruct     *font1;
             XmFontListEntry font_list_entry;
             XmFontList font_list;
             XmString  label_text;
             char *tagb;  /* Font list element tag */
             char *fontx; /* Initialize to XLFD or font alias */
             char *button_label;   /* Contains button label text */
                     .
                     .
             font1 = XLoadQueryFont (XtDisplay(toplevel), fontx);
             font_list_entry = XmFontListEntryCreate (tagb, XmFONT_IS_FONT,
                     (XtPointer)font1);
             font_list = XmFontListAppendEntry (NULL, font_list_entry);
             XmFontListEntryFree (font_list_entry);

             label_text = XmStringCreate (button_label, tagb);

             XXLLooaaddQQuueerryyFFoonntt loads the font and then
             XXmmFFoonnttLLiissttEEnnttrryyCCrreeaattee creates a font list entry.  The
             application must create an entry and then append it to
             an existing font list or create a new font list, in
             either case using XXmmFFoonnttLLiissttAAppppeennddEEnnttrryy.  Because there
             is no font list in place, the previous code example has
             NULL for the font list argument.  XXmmFFoonnttLLiissttAAppppeennddEEnnttrryy
             creates a new font list called _f_o_n_t__l_i_s_t with a single
             entry, _f_o_n_t__l_i_s_t__e_n_t_r_y.  To add another entry to
             _f_o_n_t__l_i_s_t, the application can follow the same




        11-18                                        August 26, 1994







                                                Internationalization


             procedure but supply a non-NULL font list argument.

             The following figure shows the relationships between a
             compound string, a font set, and a font list when the
             font list element tag is set to XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.
             In this case, the value field is locale text.

            FFiigguurree 1111--33..  Compound String and XmFONTLIST_DEFAULT_TAG



        11.2.4  TTeexxtt aanndd TTeexxttFFiieelldd WWiiddggeettss aanndd FFoonntt LLiissttss


             The Text and TextField widgets display text
             information.  To do so, they must be able to select the
             correct font in which to display the information.  The
             Text and TextField widgets follow a set search pattern
             to find the correct font:

               1.  Search the font list for an entry that is a font
                   set and has a font list element tag of
                   XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.  If a match is found, use
                   that font list entry.  No further searching
                   occurs.

               2.  Search the font list for an entry that specifies
                   a font set.  Use the first one found.

               3.  If no font set is found, use the first font in
                   the font list.

             A font set is desired because that insures that there
             are glyphs for every character in the locale.



        11.3  LLooccaalliizziinngg AApppplliiccaattiioonnss


             An internationalized application can be tailored to
             operate in many areas of the world, each with its own
             requirements for the language and customs to be used.
             This section explains some methods for localizing an
             application.

             The following section describes how the user, the
             application developer, and the implementation combine
             to establish the language environment of the
             application.  It then discusses two general approaches
             to localizing applications.  Succeeding sections focus




        August 26, 1994                                        11-19







        OSF/Motif Programmer's Guide


             on four aspects of localizing information in Motif
             programs:

                +o Resource files

                +o UID files

                +o Message catalogs

                +o X bitmap files

             Many aspects of localization depend on the particular
             operating system, Motif implementation, and user
             environment in which the application runs.  The
             following must all cooperate for correct localization
             to occur:

                +o The operating system's locale mechanism, if any

                +o The Motif implementation

                +o The application itself

                +o The user's system administrator

                +o The user's language environment



        11.3.1  TTeecchhnniiqquueess ffoorr LLooccaalliizzaattiioonn


             Although there are different methods for localizing an
             application, there are some common considerations:

                +o The application should not explicitly code any
                  language-dependent information in the application.
                  This includes strings, fonts, and language-
                  dependent pixmaps.

                +o The application should isolate text, fonts, and
                  pixmaps, and translate them into the languages
                  needed.  Usually this information is stored in
                  separate directories by language.











        11-20                                        August 26, 1994







                                                Internationalization


        11.3.1.1  EEssttaabblliisshhiinngg tthhee LLaanngguuaaggee EEnnvviirroonnmmeenntt


             The term _l_a_n_g_u_a_g_e _e_n_v_i_r_o_n_m_e_n_t refers to the set of
             localized data that the application needs in order to
             run correctly in the user specified locale.  A language
             environment supplies the rules associated with a
             specific language.  In addition, the language
             environment consists of any externally stored data,
             such as localized strings or text used by the
             application.  For example, the menu items displayed by
             an application might be stored in separate files for
             each language supported by the application.  This type
             of data can be stored in resource files, UID files, or,
             on XPG3-compliant systems, message catalogs.

             A single language environment is established when an
             application executes.  The actual language environment
             in which an application operates is specified by the
             application user, often either by setting an
             environment variable (LLAANNGG on POSIX-based systems) or
             by setting the xxnnllLLaanngguuaaggee resource.  The application
             then sets the language environment based on the user's
             specification.  The application can do this either by
             using sseettllooccaallee in a language procedure established by
             XXttSSeettLLaanngguuaaggeePPrroocc, or by using a method that does not
             call sseettllooccaallee.  In either case, Xt caches a per-
             display language string that is used by
             XXttRReessoollvveePPaatthhnnaammee to find resource, bitmap, and UIL
             files.

             An application that supplies a language procedure may
             either provide its own or use an Xt default procedure.
             In either case, the application establishes the
             language procedure by calling XXttSSeettLLaanngguuaaggeePPrroocc before
             calling XXttAAppppIInniittiiaalliizzee.  When a language procedure is
             installed, Xt calls it in the process of constructing
             the initial resource database.  Xt uses the value
             returned by the language procedure as its per-display
             language string.

             The default language procedure performs the following
             tasks:

                +o Sets the locale.  On ANSI C-based systems, this is
                  done by using the following code:

                  setlocale(LC_ALL, _l_a_n_g_u_a_g_e);

                  where _l_a_n_g_u_a_g_e is the value of xxnnllLLaanngguuaaggee or the
                  empty string ("") if xxnnllLLaanngguuaaggee is not set.  When




        August 26, 1994                                        11-21







        OSF/Motif Programmer's Guide


                  xxnnllLLaanngguuaaggee is not set, the locale is generally
                  derived from an environment variable (LLAANNGG on
                  POSIX-based systems).

                +o Calls XXSSuuppppoorrttssLLooccaallee to verify that the locale
                  just set is supported.  If not, a warning message
                  is issued and the locale is set to "C."

                +o Calls XXSSeettLLooccaalleeMMooddiiffiieerrss specifying the empty
                  string.

                +o Returns the value of the current locale.  On ANSI
                  C-based systems, this is the result of calling:

                  setlocale(LC_ALL, NULL);

             The application can use the default language procedure
             by making the call to XXttSSeettLLaanngguuaaggeePPrroocc in this manner:

             XtSetLanguageProc(NULL, NULL, NULL);
                .
                .
             toplevel = XtAppinitialize(...);

             By default, Xt does not install any language procedure.
             If the application does not call XXttSSeettLLaanngguuaaggeePPrroocc, Xt
             uses as its per-display language string the value of
             the xxnnllLLaanngguuaaggee resource if it is set.  If xxnnllLLaanngguuaaggee
             is not set, Xt derives the language string from the
             environment.  On POSIX-based systems, this is the value
             of the LLAANNGG environment variable.

             It is important to note that the per-display language
             string that results from this process is implementation
             dependent and that Xt provides no public means of
             examining the language string once it is established.
             The following vary by operating system and by Motif
             implementation:

                +o The mechanism, if any, used to set the locale

                +o On ANSI C-based systems, the value returned by
                  sseettllooccaallee

                +o The possible values of any environment variables
                  used to establish the language environment

                +o Whether or not xxnnllLLaanngguuaaggee is used and, if so, its
                  possible values






        11-22                                        August 26, 1994







                                                Internationalization


             Furthermore, by supplying its own language procedure,
             an application may use any procedure it wants for
             setting the language string.



        11.3.1.2  UUssiinngg LLooccaalleess


             The locale provides local information to an application
             based on the user's language, territory, and codeset.
             Both language and territory are needed because some
             languages are spoken in more than one country and more
             than one language may be spoken in some countries
             (Belgium, Canada, and Switzerland are examples).

             Information in resource, UID, and image files can be
             localized and stored in separate directories by
             language.  The Xt function XXttRReessoollvveePPaatthhnnaammee uses the
             run-time locale to determine the proper directory to
             use.

             On XPG3-compliant systems, an application can use
             message catalogs to localize text and messages.  A
             message catalog file exists for each language, and each
             is usually stored in a separate directory by language.

             The locale method of localizing compound strings and
             font lists consists of the following steps:

               1.  Establish a language procedure before calling
                   XXttAAppppIInniittiiaalliizzee.  The language procedure calls
                   sseettllooccaallee.

               2.  Localize the compound strings and font lists
                   using resource files, message catalogs, or UID
                   files.  Normally, do not specify any font list
                   element tags other than XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

               3.  Use font sets in resource or UID file font lists.

               4.  Use XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd to create compound
                   strings in the program.  This function only has
                   one argument, a text string, and automatically
                   sets the font list element tag to
                   XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

             The run-time locale determines which fonts are used to
             display text.  This is accomplished in the following
             manner:





        August 26, 1994                                        11-23







        OSF/Motif Programmer's Guide


                +o Motif calls XXttRReessoollvveePPaatthhnnaammee to load resource or
                  UID files that specify the names of fonts for font
                  sets.  XXttRReessoollvveePPaatthhnnaammee uses a file search path
                  that may vary depending on the display's language
                  string.

                +o XXCCrreeaatteeFFoonnttSSeett uses the locale to determine the
                  fonts to be used from the base font name and the
                  locale charset.

             In this method, the application usually does not
             specify font list element tags other than
             XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.  It is possible to supply
             explicit font list element tags with locale-dependent
             text.  For example, text might be displayed using large
             and small fonts or bold and italic fonts.  The
             application can do this with special tags in both the
             compound string and the font list associated with it.
             In the font list, match the tag with a font set
             specification that supplies the desired attribute
             (point size, for example).  When the application
             creates the font set, the charset comes from the
             locale.  For example, a resource file might specify a
             font list in the following manner to obtain fonts with
             a different point size:

             *fontList:  -*-*-*-R-Normal--*-120-100-100-*-*:,\
                         -*-*-*-R-Normal--*-180-100-100-*-*:BIG,\
                         -*-*-*-R-Normal--*-80-100-100-*-*:SMALL

             In this case, the application should also map the tags
             to XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG in the Motif registry of font
             list element tags.  See Section 11.4.2 for more
             information.



        11.3.1.3  LLooccaalliizzaattiioonn WWiitthhoouutt LLooccaalleess



             In this method, the locale is not set in the program,
             and a language procedure is not needed.  Instead, the
             user specifies the language environment using either
             xxnnllLLaanngguuaaggee or an environment variable such as LLAANNGG.
             Resource, UID, and image files are localized and stored
             in separate directories by language, as they are when
             the application uses locales.  XXttRReessoollvveePPaatthhnnaammee uses
             the display's language string in the same way to
             determine the proper locations of these files.





        11-24                                        August 26, 1994







                                                Internationalization


             Message catalogs are not used in this method.  Also, in
             this case Text and TextField cannot accommodate 16-bit
             data.

             The nonlocale method of localizing compound strings and
             font lists consists of these steps:

               1.  Localize compound strings using UIL files.  Note
                   that resource files cannot be used for compound
                   strings because the string-to-compound-string
                   converter always uses the font list element tag
                   XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.  Localized font lists can
                   appear in resource files.

               2.  Specify explicit font list element tags _o_t_h_e_r
                   than XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG in both compound
                   strings and font lists.

               3.  Use font names with explicit charset components
                   in resource or UIL files.  Do not use font sets.

               4.  To create compound strings in the program, use
                   XXmmSSttrriinnggCCrreeaattee with the font list element tag set
                   to something other than XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.



        11.3.2  RReessoouurrcceess aanndd LLooccaalliizzaattiioonn


             The resources used in an application that are subject
             to internationalization are stored in files external to
             the application.  These resources include

                +o All labels, particularly those that identify
                  controls.  Such labels are defined as type
                  XXmmSSttrriinngg, meaning they are compound strings.

                +o Text strings; that is, strings of text that are
                  not compound strings.

                +o Font lists.













        August 26, 1994                                        11-25







        OSF/Motif Programmer's Guide


        11.3.2.1  IInniittiiaall RReessoouurrccee DDaattaabbaassee


             The information in the external resource files is used
             when Xt builds the initial resource database.  The
             XXttDDiissppllaayyIInniittaalliizzee function loads the resource database
             by merging in resources from the following sources, in
             order of precedence (that is, each component takes
             precedence over the following components):

                +o The application command line

                +o A per-host user environment resource file on the
                  local host

                +o Screen-specific resources for the default screen
                  of the display

                +o A resource property on the server or user
                  preference resource file on the local host

                +o An application-specific user resource file on the
                  local host

                +o An application-specific class resource file on the
                  local host

             Localization applies to two components of the initial
             resource database-the application-specific user and
             class resources.  Localized resources that are
             controlled by the programmer are in the application
             class resource file, and localized resources that are
             controlled by the user are in the user resource file.
             Note that the user resources take precedence over the
             application class resources.



        11.3.2.2  RReessoouurrccee FFiillee LLooccaattiioonnss



             XXttDDiissppllaayyIInniittiiaalliizzee calls XXttRReessoollvveePPaatthhnnaammee to load
             both the user and the class resources.

             To load the user's application resource file,
             XXttDDiissppllaayyIInniittiiaalliizzee uses the value of the
             XXUUSSEERRFFIILLEESSEEAARRCCHHPPAATTHH environment variable as the search
             path.  If that variable is not set or if the search
             path fails to find the file, and if the environment
             variable XXAAPPPPLLRREESSDDIIRR is defined, XXttDDiissppllaayyIInniittiiaalliizzee




        11-26                                        August 26, 1994







                                                Internationalization


             next tries an implementation-dependent search path with
             a number of entries that include XXAAPPPPLLRREESSDDIIRR and the
             user's home directory.  If XXAAPPPPLLRREESSDDIIRR is not set or if
             that search path fails, XXttDDiissppllaayyIInniittiiaalliizzee tries
             another implementation-dependent search path with a
             number of entries that include the user's home
             directory.

             To load the application-specific class resource file,
             XXttDDiissppllaayyIInniittiiaalliizzee uses the value of the
             XXFFIILLEESSEEAARRCCHHPPAATTHH environment variable as the search
             path.  If that variable is not set or if the search
             path fails to find the file, XXttDDiissppllaayyIInniittiiaalliizzee tries
             an implementation-dependent search path.

             The search paths for both resource files may contain
             any substitutions recognized by XXttRReessoollvveePPaatthhnnaammee.
             That routine substitutes the display's language string
             for %%LL.  In an implementation-dependent manner, it
             substitutes the language, territory, and codeset
             components of the language string for %%ll, %%tt, and %%cc,
             respectively.  This mechanism allows Xt to load
             different resource files for different languages, as
             specified by the display's language string.

             The display's language string is determined by the
             application's language procedure, if present, or else
             by the value of the xxnnllLLaanngguuaaggee resource or by the
             environment.  The language string associated with any
             particular language and the search paths used to find
             the resource files depend on the system vendor, the
             Motif vendor, the application, and the user's system
             administrator.  Determining the actual directories in
             which localized resource files reside requires
             coordination among all these sources.

             In general, an application developer prepares a set of
             localized application class resource files, one for
             each language the application supports.  The developer
             may also need to supply a language procedure
             appropriate for one or more of the systems on which the
             application will run.  The application vendor must
             arrange for the resource files to be installed in the
             correct directories, depending on the operating system
             and the Motif implementation on which the application
             will run.









        August 26, 1994                                        11-27







        OSF/Motif Programmer's Guide


        11.3.2.3  AAnn EExxaammppllee



             Following is an example of an application class
             defaults file for a simple program that creates a
             MainWindow with a Text widget.  The font list
             specification includes a single font set with a default
             tag.  This resource file would be appropriate for an
             application that uses locales.

             *fontList:                 -*-*-*-R-Normal--*-180-100-100-*-*:
             *Text1.value:\
             Hier ist etwas Text fur das Text Widget.\n\
             Gemischter 8-und 16-bit Text.
             *version_box.messageString:     Dies ist i18n Demo Version
             *version_box.okLabelString:     Schliessen
             *version_box.dialogTitle:       I18n Demo Version
             *pgm_ver_btn.labelString:       I18n Demo Version
             *events_btn.labelString:        Aktionen
             *help_btn_menu.labelString:     Hilfe
             *help_btn_cascade.labelString:  Hilfe
             *help_box.messageString:        Leider ist keine Hilfe hier.
             *help_box.okLabelString:        Schliessen
             *help_box.dialogTitle:          i18n Demo Hilfe
             *stop_btn.labelString:          Enden



        11.3.3  UUIILL aanndd LLooccaalliizzaattiioonn



             The general models for localizing applications using
             UIL are the same as those for applications that do not
             use UIL.  An application developer creates separate UIL
             files, each containing string and resource values for a
             particular language.  UIL files can also be used in
             conjuction with localized resource and pixmap files.
             As with localization of resource files, there are two
             basic approaches to localizing UIL files: one that uses
             locales and one that does not.













        11-28                                        August 26, 1994







                                                Internationalization


        11.3.3.1  PPrreeppaarriinngg LLooccaalliizzeedd UUIIDD FFiilleess



             When using locales with UIL, an application developer
             should take the following steps:

                +o Do not use a cchhaarraacctteerr__sseett declaration for the
                  module.

                +o When creating compound strings in a UIL file, use
                  double quotes and no character set specification
                  for the text.

                +o When creating font lists in a UIL file, use font
                  sets, not fonts.  Do not specify character sets
                  for the font sets.

                +o Before compiling a UIL file using the uuiill command,
                  set up any environment variables (such as LLAANNGG) or
                  other mechanisms the system vendor recommends to
                  establish the locale that is appropriate for the
                  UIL file to be compiled.  Invoke the uuiill command
                  with the --ss option.  This enables the UIL compiler
                  to set the locale and parse double quoted strings
                  without explicit character sets in the locale's
                  encoding.  It also ensures that localized compound
                  strings and font list entries are created with
                  font list element tags of XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

                +o Before using the UUiill function to compile a UIL
                  file, set the locale that is appropriate for the
                  UIL file to be compiled.  In the UUiill__ccoommmmaanndd__ttyyppee
                  structure that is the first argument to the UUiill
                  function, set the uussee__sseettllooccaallee__ffllaagg member to 1.
                  This has the same effect as invoking the uuiill
                  command with the --ss option.

             When localizing UIL files without using locales, an
             application developer should take the following steps:

                +o When using single quotes for the text of compound
                  strings, supply a cchhaarraacctteerr__sseett declaration for
                  the module.

                +o When using double quotes for the text of compound
                  strings, supply an explicit character set for each
                  segment.

                +o When creating font lists in a UIL file, use fonts,
                  not font sets.  Specify an explicit character set




        August 26, 1994                                        11-29







        OSF/Motif Programmer's Guide


                  for each font.

                +o When compiling a UIL file using the uuiill command,
                  do not invoke the command with the --ss option.  The
                  UIL compiler does not set the locale, and it
                  parses each string using rules derived from the
                  explicitly specified character set for that
                  string.

                +o When compiling a UIL file using the UUiill function,
                  set the uussee__sseettllooccaallee__ffllaagg member of the
                  UUiill__ccoommmmaanndd__ttyyppee structure to 0.  This has the
                  same effect as invoking the uuiill command without
                  the --ss option.

             The UIL compiler processes a single source file for
             each invocation of the uuiill command or the UUiill function.
             However, UIL has an iinncclluuddee ffiillee directive that is
             similar to the C preprocessor's ##iinncclluuddee directive.  If
             the file argument for this directive is not an absolute
             pathname, the compiler searches for the file in a
             series of directories.  These include the directory of
             the main UIL source file and any directories specified
             via the --II option to the uuiill command or the iinncclluuddee__ddiirr
             member of the UUiill__ccoommmmaanndd__ttyyppee structure for the UUiill
             function.

             One strategy for maintaining localized UIL source files
             is to place only language-independent information in
             the main UIL source file and to put all language-
             dependent information in included files that are in
             separate directories for each language.  Then a
             developer can compile the UIL files for different
             languages without editing any UIL files.  When using
             locales, a developer first sets up the environment for
             the intended locale.  Whether using locales or not, the
             developer then invokes the UIL compiler with the proper
             include directory for the intended language.

             In general, a developer can mix localized UIL files
             with localized resource files.  For example, the
             developer might specify compound strings in UIL files
             and font lists in resource files.  Note one exception:
             it is not practical to use resource files to localize
             compound strings without using locales.  This is
             because no resource file syntax exists for supplying an
             explicit font list element tag for a compound string.

             For resource values that the user may override, the
             developer must use resource files or fallback
             resources, or must in some way ensure that the user's




        11-30                                        August 26, 1994







                                                Internationalization


             resource settings can override the developer's settings
             from the UIL file.



        11.3.3.2  MMRRMM aanndd LLooccaalliizzeedd UUIIDD FFiilleess



             Once the developer has generated localized UID files,
             the vendor and the user's system administrator must
             arrange for these files to be installed in the
             appropriate directories for the system where the
             program is to run.  As with resource files, these
             directories depend on configurations established by the
             operating system vendor, the Motif vendor, and the
             system administrator.

             MMrrmmOOppeennHHiieerraarrcchhyyPPeerrDDiissppllaayy takes as an argument a list
             of names of UID files.  It calls XXttRReessoollvveePPaatthhnnaammee to
             find each file the list.  If a filename is an absolute
             pathname, that pathname is the search path for
             XXttRReessoollvveePPaatthhnnaammee.  Otherwise,
             MMrrmmOOppeennHHiieerraarrcchhyyPPeerrDDiissppllaayy constructs a search path in
             the following way:

                +o If the environment variable UUIIDDPPAATTHH is set, the
                  value of that variable is the search path.

                +o If UUIIDDPPAATTHH is not set, but XXAAPPPPLLRREESSDDIIRR is set,
                  MMrrmmOOppeennHHiieerraarrcchhyyPPeerrDDiissppllaayy uses a default search
                  path with entries that include $$XXAAPPPPLLRREESSDDIIRR, the
                  user's home directory, and vendor-dependent system
                  directories.

                +o If neither UUIIDDPPAATTHH nor XXAAPPPPLLRREESSDDIIRR is set,
                  MMrrmmOOppeennHHiieerraarrcchhyyPPeerrDDiissppllaayy uses a default search
                  path with entries that include the user's home
                  directory and vendor-dependent system directories.

             These paths may include the substitution field %%UU.  In
             each call to XXttRReessoollvveePPaatthhnnaammee,
             MMrrmmOOppeennHHiieerraarrcchhyyPPeerrDDiissppllaayy substitutes the current
             filename from the list of UID files for %%UU.  The paths
             may also include other substitution fields accepted by
             XXttRReessoollvveePPaatthhnnaammee.  In particular, XXttRReessoollvveePPaatthhnnaammee
             substitutes the display's language string for %%LL, and
             it substitutes the components of the display's language
             string (in a vendor-dependent way) for %%ll, %%tt, and %%cc.
             If necessary MMrrmmOOppeennHHiieerraarrcchhyyPPeerrDDiissppllaayy searches the
             path twice, first with %%SS mapped to ..uuiidd and then with




        August 26, 1994                                        11-31







        OSF/Motif Programmer's Guide


             %%SS mapped to NULL.  The substitution field %%TT is always
             mapped to uuiidd.

             The usual mechanism for employing localized UID files
             is to use a search path that contains one of the
             substitutions derived from the display's language
             string.  As with resource files, the vendor and system
             administrator must ensure that the directories where
             the localized UID files reside match the display's
             language string (or the appropriate component of the
             language string).



        11.3.4  MMeessssaaggee CCaattaallooggss aanndd LLooccaalliizzaattiioonn



             On an XPG3-compliant system, an application can use
             message catalogs to localize text.  The format of
             message catalogs is implementation dependent, and the
             application must take steps to coordinate the locations
             of the message catalogs with the locations of resource,
             UID, and image files.  Use of message catalogs requires
             the following steps:

                +o Using an implementation-dependent method, prepare
                  a separate message catalog containing text to be
                  localized for each language.

                +o Arrange to have the message catalogs installed in
                  the appropriate directories on the systems on
                  which the application will run.

                +o Arrange for the user's environment to be set up
                  correctly so that the application can read the
                  message catalog appropriate to the language.

                +o In the program, use the ccaattooppeenn function to open a
                  message catalog and the ccaattcclloossee function to close
                  it.

                +o Use the ccaattggeettss function to read text from an open
                  message catalog.

                +o If necessary, convert the text to the target
                  format (such as a compound string) and, for
                  resources, supply the text in the appropriate
                  widget creation argument list or call to
                  XXttSSeettVVaalluueess.





        11-32                                        August 26, 1994







                                                Internationalization


             The ccaattooppeenn function takes as an argument the name of
             the message catalog file.  If this is an absolute
             pathname, ccaattooppeenn opens that file.  Otherwise, ccaattooppeenn
             uses the value of the NNLLSSPPAATTHH environment variable as a
             search path.  This path can contain a number of
             substitution fields.  The filename passed to ccaattooppeenn is
             substituted for %%NN.  The value of the LLAANNGG environment
             variable is substituted for %%LL, and its language,
             territory, and codeset components are substituted for
             %%ll, %%tt, and %%cc, respectively.

             Note that these values may not be the same as the
             display's language string or its components.  An
             application and software vendor that use message
             catalogs must coordinate the locations of message
             catalogs with those of localized resource, UID, and
             image files, which usually depend on the display's
             language string.  One possible strategy is to call
             ccaattooppeenn with an absolute pathname constructed by
             calling XXttRReessoollvveePPaatthhnnaammee with the value of NNLLSSPPAATTHH as
             the search path argument.  XXttRReessoollvveePPaatthhnnaammee
             substitutes the display's language string and its
             components for %%LL, %%ll, %%tt, and %%cc in $$NNLLSSPPAATTHH.  In this
             way, the application can use a single mechanism, the
             display's language string, to distinguish file
             locations by language.  The software vendor must still
             arrange for the user's system administrator to install
             the message catalogs in the correct locations and to
             ensure that NNLLSSPPAATTHH is appropriately set in the user's
             environment.



        11.3.5  IImmaaggeess,, PPiixxmmaappss,, aanndd LLooccaalliizzaattiioonn


             A pixmap is a screen image that is stored in memory so
             that it can be recalled and displayed when needed.
             Motif 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 need to
             be localized.

             Motif maintains caches of pixmaps and images.  The
             function XXmmGGeettPPiixxmmaappBByyDDeepptthh 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, XXmmGGeettPPiixxmmaappBByyDDeepptthh searches for an X
             bitmap file whose name matches the requested image




        August 26, 1994                                        11-33







        OSF/Motif Programmer's Guide


             name.  XXmmGGeettPPiixxmmaappBByyDDeepptthh calls XXttRReessoollvveePPaatthhnnaammee to
             search for the file.  If the requested image name is an
             absolute pathname, that pathname is the search path for
             XXttRReessoollvveePPaatthhnnaammee.  Otherwise, XXmmGGeettPPiixxmmaappBByyDDeepptthh
             constructs a search path in the following way:

                +o If the environment variable XXBBMMLLAANNGGPPAATTHH is set,
                  the value of that variable is the search path.

                +o If XXBBMMLLAANNGGPPAATTHH is not set but XXAAPPPPLLRREESSDDIIRR is set,
                  XXmmGGeettPPiixxmmaappBByyDDeepptthh uses a default search path with
                  entries that include $$XXAAPPPPLLRREESSDDIIRR, the user's home
                  directory, and vendor-dependent system
                  directories.

                +o If neither XXBBMMLLAANNGGPPAATTHH nor XXAAPPPPLLRREESSDDIIRR is set,
                  XXmmGGeettPPiixxmmaappBByyDDeepptthh uses a default search path with
                  entries that include the user's home directory and
                  vendor-dependent system directories.

             These paths may include the substitution field %%BB.  In
             each call to XXttRReessoollvveePPaatthhnnaammee, XXmmGGeettPPiixxmmaappBByyDDeepptthh
             substitutes the requested image name for %%BB.  The paths
             may also include other substitution fields accepted by
             XXttRReessoollvveePPaatthhnnaammee.  In particular, XXttRReessoollvveePPaatthhnnaammee
             substitutes the display's language string for %%LL, and
             it substitutes the components of the display's language
             string (in a vendor-dependent way) for %%ll, %%tt, and %%cc.
             The substitution field %%TT is always mapped to bbiittmmaappss,
             and %%SS is always mapped to NULL.

             As with resource and UID files, the usual mechanism for
             employing localized X bitmap files is to use a search
             path that contains one of the substitutions derived
             from the display's language string.  As with resource
             and UID files, the vendor and system administrator must
             ensure that the directories where the localized X
             bitmap files reside match the display's language string
             (or the appropriate component of the language string).

             See Chapter 12 for more information on images and
             pixmaps.













        11-34                                        August 26, 1994







                                                Internationalization


        11.3.6  CCoommppaarriinngg AApppprrooaacchheess ttoo LLooccaalliizzaattiioonn


             The locale approach allows an application to use
             existing internationalization routines.  On the other
             hand, the application is limited in portability to
             systems that support the same internationalization
             standards (XPG3, POSIX, or ANSI).  This approach is
             also only applicable to applications using a single
             language.

             The nonlocale approach only addresses the aspect of
             isolating information from the application and ensuring
             that it uses the proper localized version of this
             information.  The disadvantage is that there is more
             work for the programmer and there may be nonstandard
             functionality.  The advantages are that there is
             guaranteed portability across all platforms that
             support Motif, and that it allows handling of multiple
             character sets for specialized applications that
             require this functionality.



        11.4  AAddvvaanncceedd TTooppiiccss iinn IInntteerrnnaattiioonnaalliizzaattiioonn


             This section covers some advanced topics dealing with
             internationalization.



        11.4.1  IInntteerrnnaattiioonnaalliizzaattiioonn aanndd TTeexxtt IInnppuutt


             An application subject to internationalization presents
             some unique problems when it deals with text input.
             The application must be able to correctly interpret and
             process text input in any language.  This section
             explains how an application accomplishes this.



        11.4.1.1  IInnppuutt MMeetthhoodd


             Although there are many different keyboards in use,
             sometimes certain characters in an alphabetic language
             are not directly available on any keyboard.  In this
             case, the user must type a combination of keys to input
             the desired character.  The number of characters in an




        August 26, 1994                                        11-35







        OSF/Motif Programmer's Guide


             ideographic language far exceeds the capability of any
             keyboard and makes it impossible to have a keyboard
             with all of the language's symbols.  In this case,
             input is usually accomplished based on the language's
             phonetics.  These cases illustrate the concept of an
             input method.  An input method is simply the mechanism
             that is used to map between the keys typed by a user
             and the resulting characters that are input to the
             application.  A common feature of many input methods is
             that the application user may type combinations of keys
             to create a single character.  Creating characters from
             keystrokes is called pprree--eeddiittiinngg.

             Input methods may require several areas to display the
             actual keystrokes.

                +o The ssttaattuuss aarreeaa is an output-only window that
                  identifies the style of input (phonetic, numeric,
                  stroke and radial, and so on) and the current
                  status of an input method interaction.

                +o The pprree--eeddiitt aarreeaa displays the intermediate text
                  for languages that are composed before the
                  application acts on the data. There are several
                  possible locations for the pre-edit area:

                  OOvveerr--tthhee--ssppoott
                            Displays the data in an input method
                            window that is placed over the point of
                            insertion.

                  OOffff--tthhee--ssppoott
                            Displays the pre-edit window inside the
                            application window (usually at the
                            bottom) but not at the point of
                            insertion.

                  RRoooott--wwiinnddooww
                            Uses a pre-edit window that is a child
                            of the root window.

                  A VendorShell resource, XXmmNNpprreeeeddiittTTyyppee determines
                  which style is used for a Text or TextField input
                  method.  The syntax, possible values, and default
                  value of this resource are implementation
                  dependent.

                +o The aauuxxiilliiaarryy aarreeaa is used for popup menus and
                  customizing dialogs that some input methods use.






        11-36                                        August 26, 1994







                                                Internationalization


             Input methods are supplied by vendors and are
             implementation dependent.  The VendorShell resource
             XXmmNNiinnppuuttMMeetthhoodd is an implementation-dependent string
             that specifies the input method portion of the locale
             modifiers.  If a value is supplied for this resource,
             Motif uses it to set the locale modifiers before
             opening an input method for Text or TextField.

             The following figure shows one possible program window
             with a Text widget using over-the-spot interaction for
             Japanese text input.  The status area indicates that
             phonetic input is in use and insert mode is enabled.
             The pre-edit area shows that the letter "H" has been
             entered.  Since there is no Hiragana phonetic
             equivalent, the "H" appears in the pre-edit window.

          FFiigguurree 1111--44..  Text Widget Pre-Edit and Status Areas Using
                        Over-the-Spot

             The following figure shows the same window after a "u"
             has been entered following the "H" shown in the
             previous figure.

          FFiigguurree 1111--55..  Text Widget Pre-Edit Area After Next Character
                        Entry

             Here the pre-edit area is displaying the phonetic
             equivalent of the English letters "hu" in Hiragana.



        11.4.1.2  IInnppuutt CCoonntteexxtt


             An iinnppuutt ccoonntteexxtt is the mechanism used to provide the
             state information needed to manage the information flow
             between the application and the input method.  It is a
             combination of an input method, a locale specifying the
             encoding of character strings to be returned, an
             application window, and internal state information.
             The following figure shows the relationships involved.
             The input method is determined by the locale specified
             by the application user.












        August 26, 1994                                        11-37







        OSF/Motif Programmer's Guide


                 FFiigguurree 1111--66..  Input Method and Input Contexts



        11.4.1.3  IInnppuutt aanndd tthhee MMoottiiff TTeexxtt WWiiddggeett


             The Motif Text and TextField widgets, when editable,
             provide a transparent connection to the locale-specific
             input method for text input.  The application
             programmer specifies an appropriate font set in the
             Text or TextField XXmmNNffoonnttLLiisstt resource and creates
             either widget as a descendant of VVeennddoorrSShheellll.
             VendorShell provides geometry management of the status
             and pre-edit areas.  It also supplies a visual
             separator between the status area window and the
             application's top level window.

             Setting the VVeennddoorrSShheellll resource XXmmNNpprreeeeddiittTTyyppee
             dictates the location of the input method window.  With
             an off-the-spot input method, the pre-edit and status
             area windows appear at the bottom of the application
             window.



        11.4.1.4  TTeexxtt IInnppuutt UUssiinngg aa DDrraawwiinnggAArreeaa



             An application that needs special text processing may
             use a DrawingArea for text input and output.  For
             internationalized text input with any widget other than
             Text or TextField, the application must use the Xlib
             input method facilities.  These allow the application
             to open an input method and input context and to obtain
             input from the input method.  When using these
             facilities, an application may also need to handle
             input method geometry management, focus management,
             event filtering, and other issues.  For more
             information, see _X_l_i_b-_C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e.



        11.4.1.5  GGeeoommeettrryy MMaannaaggeemmeenntt ooff PPrree--EEddiitt aanndd SSttaattuuss AArreeaass


             When an off-the-spot input method is used with the Text
             or TextField widget, the pre-edit and status areas are
             below the client's main window but inside the
             VendorShell.  VendorShell accomplishes the necessary




        11-38                                        August 26, 1994







                                                Internationalization


             geometry management.  If the application uses either
             XXttGGeettVVaalluueess or XXttSSeettVVaalluueess to get or set the height
             (XXmmNNhheeiigghhtt) of VVeennddoorrSShheellll, the height includes the
             height of the input method area.

             The following figure shows a Text widget using an off-
             the-spot input method.  The distance "h" is the
             additional height that the input manager needs to
             display the status and pre-edit areas.  Note that in
             off-the-spot, the pre-edit area is at the bottom of the
             interaction.

          FFiigguurree 1111--77..  Text Widget Pre-Edit and Status Areas Using
                        Off-the-Spot



        11.4.2  CCoommppoouunndd SSttrriinnggss aanndd CCoommppoouunndd TTeexxtt


             Compound text is the standard format for exchanging
             textual data between X window system applications.
             This is necessary when the user moves text displayed in
             one codeset to another window with text in a different
             codeset.  For example, the following figure shows two
             windows, one titled "UJIS" and the other titled "Shift
             JIS."

                     FFiigguurree 1111--88..  Reason for Compound Text

             Both windows represent a Motif Text widget, one with
             some Japanese UJIS characters displayed, and the other
             with some Shift JIS characters.  If the user wants to
             cut text from one window and paste it in the other
             window, compound text is used to pass data between the
             two.  The Motif Text widget does this automatically.

             If one of the widgets in the previous figure is a Label
             widget instead of a Text widget, a different situation
             exists.  This is because the Label widget has its text
             data in compound string format, while the text widget
             data is a simple character string.  In order to pass
             text data between a Text or TextField widget and any
             other widget, the application needs to convert the
             compound string to compound text.

             Motif has two functions, XXmmCCvvttXXmmSSttrriinnggTTooCCTT and
             XXmmCCvvttCCTTTTooXXmmSSttrriinngg, for converting between compound
             strings and compound text.






        August 26, 1994                                        11-39







        OSF/Motif Programmer's Guide


             XXmmCCvvttXXmmSSttrriinnggTTooCCTT converts a compound string to
             compound text.  The converter uses the font list tag
             associated with a given compound string segment to
             select a compound text format for that segment.  A
             registry defines a mapping between font list tags and
             compound text encoding formats.  The converter uses the
             following algorithm for each compound string segment:

               1.  If the compound string segment tag is mapped to
                   XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG in the registry, the
                   converter passes the text of the compound string
                   segment to XXmmbbTTeexxttLLiissttTTooTTeexxttPPrrooppeerrttyy with an
                   encoding style of XXCCoommppoouunnddTTeexxttSSttyyllee and uses the
                   resulting compound text for that segment.

               2.  If the compound string segment tag is mapped to
                   an MIT registered charset in the registry, the
                   converter creates the compound text for that
                   segment using the charset (from the registry) and
                   the text of the compound string segment as
                   defined in the X Consortium Standard _C_o_m_p_o_u_n_d
                   _T_e_x_t _E_n_c_o_d_i_n_g.

               3.  If the compound string segment tag is mapped to a
                   charset in the registry that is neither
                   XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG nor an MIT registered
                   charset, the converter creates the compound text
                   for that segment using the charset (from the
                   registry) and the text of the compound string
                   segment as an "extended segment" with a variable
                   number of octets per character.

               4.  If the compound string segment tag is not mapped
                   in the registry, the result is implementation
                   dependent.

             An application can use XXmmRReeggiisstteerrSSeeggmmeennttEEnnccooddiinngg to map
             a font list element tag to a compound text encoding
             format.  For example, the application may be using a
             font list element tag of "BOLD" to identify a compound
             text segment consisting of localized text to be
             displayed in a bold font.  To ensure that the segment
             is treated as localized text when converted to compound
             text, the tag "BOLD" should be mapped to
             XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG as follows:

             char *old_encoding = XmRegisterSegmentEncoding("BOLD",
                                      XmFONTLIST_DEFAULT_TAG);
             XtFree(old_encoding);






        11-40                                        August 26, 1994







                                                Internationalization


             XXmmCCvvttCCTTTTooXXmmSSttrriinngg converts compound text to a compound
             string.  This function is implementation dependent.

             See Chapter 16 for more information on transferring
             data between applications.  The compound text format is
             described in the X Consortium Standard _C_o_m_p_o_u_n_d _T_e_x_t
             _E_n_c_o_d_i_n_g.
















































        August 26, 1994                                        11-41





 
