634 lines
44 KiB
Plaintext
634 lines
44 KiB
Plaintext
<!-- $XConsortium: ch04.sgm /main/8 1996/09/08 19:39:21 rws $ -->
|
|
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1995 Novell, Inc. -->
|
|
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1995 Hitachi. -->
|
|
|
|
<chapter id="IPG.motif.div.1">
|
|
<title id="IPG.motif.mkr.1">Xt, Xlib, and Motif Dependencies</title>
|
|
<para>For information on Xt and Xlib dependencies, refer to Chapter 13 of <citetitle>Xlib — C Language Interface</citetitle>.</para>
|
|
<para>The rest of this chapter discusses tasks related to internationalizing
|
|
with Motif.</para>
|
|
<sect1 id="IPG.motif.div.2">
|
|
<title id="IPG.motif.mkr.2">Locale Management<indexterm><primary>language
|
|
environment</primary><secondary>description</secondary></indexterm><indexterm>
|
|
<primary>environment, language</primary></indexterm></title>
|
|
<para>The term <emphasis>language environment</emphasis> refers to the set
|
|
of localized data that the application needs 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, User Interface Definition (UID) files, or message
|
|
catalogs (on XPG3-compliant systems).</para>
|
|
<para>A single language environment is established when an application runs.
|
|
The language environment in which an application operates is specified by
|
|
the application user, often either by setting an environment variable ( <systemitem>LANG</systemitem> or <systemitem>LC_*</systemitem> on POSIX-based systems)
|
|
or by setting the xnlLanguage resource. The application then sets the language
|
|
environment based on the user's specification. The application can do this
|
|
by using the <computeroutput>setlocale()</computeroutput> function in a language
|
|
procedure established by the <computeroutput>XtSetLanguageProc()</computeroutput>
|
|
function. This causes Xt to cache a per-display language string that is used
|
|
by the <computeroutput>XtResolvePathname()</computeroutput> function to find
|
|
resource, bitmap, and User Interface Language (UIL) files.</para>
|
|
<para>An application that supplies a language procedure can either provide
|
|
its own procedure or use an Xt<indexterm><primary>language procedure</primary>
|
|
</indexterm> default procedure. In either case, the application establishes
|
|
the language procedure by calling the <computeroutput>XtSetLanguageProc()</computeroutput> function before initializing the toolkit and before loading
|
|
the resource databases (such as by calling the <computeroutput>XtAppInitialize()</computeroutput> function). 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.</para>
|
|
<para>The default language procedure performs the following tasks:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para>Sets the locale. This is done
|
|
by using:</para>
|
|
<programlisting>setlocale(LC_ALL, <symbol role="Variable">language</symbol>);</programlisting>
|
|
<para>where <symbol role="Variable">language</symbol> is the value of the <systemitem>xnlLanguage</systemitem> resource, or the empty string (“”) if
|
|
the <systemitem>xnlLanguage</systemitem> resource is not set. When the <systemitem>xnlLanguage</systemitem> resource is not set, the locale is generally derived
|
|
from an environment variable (<systemitem>LANG</systemitem> on POSIX-based
|
|
systems).</para>
|
|
</listitem><listitem><para>Calls the <computeroutput>XSupportsLocale()</computeroutput>
|
|
function to verify that the locale just set is supported. If not, a warning
|
|
message is issued and the locale is set to C.</para>
|
|
</listitem><listitem><para>Calls the <computeroutput>XSetLocaleModifiers()</computeroutput> function specifying the empty string.</para>
|
|
</listitem><listitem><para>Returns the value of the current locale. On ANSI
|
|
C-based systems, this is the result of calling:</para>
|
|
<programlisting>setlocale(LC_ALL, NULL);</programlisting>
|
|
</listitem></itemizedlist>
|
|
<para>The application can use the default language procedure by making the
|
|
call to the <computeroutput>XtSetLanguageProc()</computeroutput> function
|
|
in the following manner:</para>
|
|
<programlisting>XtSetLanguageProc(NULL, NULL, NULL);
|
|
...
|
|
toplevel = XtAppInitialize(...);</programlisting>
|
|
<para>By default, Xt does not install any language procedure. If the application
|
|
does not call the <computeroutput>XtSetLanguageProc()</computeroutput> function,
|
|
Xt uses as its per-display language string the value of the <systemitem>xnlLanguage</systemitem> resource if it is set. If the <systemitem>xnlLanguage</systemitem> resource is not set, Xt derives the language string from the <systemitem>LANG</systemitem> environment variable. <literal><indexterm><primary>XtSetLanguageProc</primary><secondary>default language</secondary></indexterm></literal></para>
|
|
<note>
|
|
<para>The per-display language string that results from this process is implementation-dependent,
|
|
and Xt provides no public means of examining the language string once it
|
|
is established.</para>
|
|
</note>
|
|
<para>By supplying its own language procedure, an application can use any
|
|
procedure it wants for setting the language string.</para>
|
|
</sect1>
|
|
<sect1 id="IPG.motif.div.3">
|
|
<title id="IPG.motif.mkr.3">Font Management</title>
|
|
<para>The desktop uses render tables to display text. A render table is a tagged
|
|
collection of renditions, each of which specifies the data used in rendering
|
|
compound strings. For information on renditions, and render tables, refer
|
|
to &MotifProgGd;.</para>
|
|
</sect1>
|
|
<sect1 id="IPG.motif.div.11">
|
|
<title id="IPG.motif.mkr.5">Drawing Localized Text<indexterm><primary>compound
|
|
strings</primary><secondary>for international text display</secondary></indexterm><indexterm>
|
|
<primary>compound strings</primary><secondary>structures, interaction with
|
|
render tables</secondary></indexterm></title>
|
|
<para>A compound string (type <classname>XmString</classname>)is a means of
|
|
encoding text so that it can be displayed in many different fonts without
|
|
changing anything in the program. A rendition, which is identified by a rendition
|
|
tag, specifies the font (and other characteristics, such as color) with which
|
|
the compound string with that rendition tag is to be rendered.</para>
|
|
<para>Especially useful for internationalization purposes are render tables,
|
|
which are collections of renditions. Among the renditions in the table may
|
|
be one tagged <systemitem class="constant">_MOTIF_DEFAULT_LOCALE</systemitem>,
|
|
which is the rendition used for the current locale. For internationalized
|
|
applications, render tables should be specified in resource files.</para>
|
|
<para>The foregoing discussion provides only a brief overview of some subjects
|
|
related to drawing localized text; for complete information, refer to &MotifProgGd;.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="IPG.motif.div.18">
|
|
<title id="IPG.motif.mkr.11">Inputting Localized Text<indexterm><primary>VendorShell widget class</primary><secondary>as input manager</secondary></indexterm><indexterm>
|
|
<primary>input method</primary><secondary>VendorShell widget class</secondary>
|
|
</indexterm><indexterm><primary>VendorShell widget class</primary><secondary>geometry management</secondary></indexterm></title>
|
|
<para>In the system environment, the <computeroutput>VendorShell</computeroutput>
|
|
widget class is enhanced to provide the interface to the input method. While
|
|
the VendorShell class controls only one child widget in its geometry management,
|
|
an extension has been added to the VendorShell class to enhance it for managing
|
|
all components necessary in the interface to an input method. These components
|
|
include the status area, preedit area, and the MainWindow area.<indexterm>
|
|
<primary>VendorShell widget class</primary><secondary>managing components</secondary><tertiary>status area</tertiary></indexterm><indexterm><primary>VendorShell widget class</primary><secondary>managing components</secondary>
|
|
<tertiary>preedit area</tertiary></indexterm><indexterm><primary>VendorShell
|
|
widget class</primary><secondary>managing components</secondary><tertiary>MainWindow area</tertiary></indexterm></para>
|
|
<para>When the input method requires a status area or a preedit area or both,
|
|
the <computeroutput>VendorShell</computeroutput> widget automatically instantiates
|
|
the status and preedit areas and manages their geometry layout. Any status
|
|
area or preedit area is managed by the <computeroutput>VendorShell</computeroutput> widget internally and is not accessible by the client. The widget
|
|
instantiated as the child of the <computeroutput>VendorShell</computeroutput>
|
|
widget is called the MainWindow area.<indexterm><primary>input method</primary>
|
|
<secondary>requirements</secondary></indexterm><indexterm><primary>international
|
|
text input</primary><secondary>input methods</secondary></indexterm><indexterm>
|
|
<primary>input method</primary><secondary>international text input</secondary>
|
|
</indexterm></para>
|
|
<para>The input method to be used by the <computeroutput>VendorShell</computeroutput>
|
|
widget is determined by the <systemitem>XmNinputMethod</systemitem> resource;
|
|
for example, <computeroutput>@im=alt</computeroutput>. The default value of
|
|
Null indicates to choose the default input method associated with the locale
|
|
at the time that VendorShell is created. As such, the user can affect which
|
|
input method is selected by either setting the locale, setting the <systemitem>XmNinputMethod</systemitem> resource, or setting both. The locale name is
|
|
concatenated with the <systemitem>XmNinputMethod</systemitem> resource to
|
|
determine the input method name. The locale name must not be specified in
|
|
this resource. The modifier name for the<systemitem>XmNinputMethod</systemitem>
|
|
resource needs to be in the form <computeroutput>@im=</computeroutput><symbol role="Variable">modifier</symbol>, where modifier is the string used to qualify
|
|
which input method is selected.<indexterm><primary>input method</primary>
|
|
<secondary>determining, XmNinputMethod resource</secondary></indexterm><indexterm>
|
|
<primary>XmNinputMethod resource, determining input method</primary></indexterm></para>
|
|
<para>The <computeroutput>VendorShell</computeroutput> widget can support
|
|
multiple widgets that can share the input method. Yet only one widget can
|
|
have the keyboard focus (for example, receive key press events and send them
|
|
to an input method) at any given time. To support multiple widgets (such
|
|
as <computeroutput>Text</computeroutput> widgets), the widgets need to be
|
|
descendants of the <computeroutput>VendorShell</computeroutput> widget.</para>
|
|
<note>
|
|
<para>The <computeroutput>VendorShell</computeroutput> widget class is a superclass
|
|
of the <computeroutput>TransientShell</computeroutput> and <computeroutput>TopLevelShell</computeroutput> widget classes. As such, an instantiation
|
|
of a <computeroutput>TopLevelShell</computeroutput> or a <computeroutput>DialogShell</computeroutput> is essentially an instantiation of a <computeroutput>VendorShell</computeroutput> widget class.</para>
|
|
</note>
|
|
<para>The <computeroutput>VendorShell</computeroutput> widget behaves as an
|
|
input manager only if one of its descendants is an <computeroutput>XmText[Field]</computeroutput> instance. As soon as an <computeroutput>XmText[Field]</computeroutput>
|
|
instance is created as a descendant of the <computeroutput>VendorShell</computeroutput>
|
|
widget, <computeroutput>VendorShell</computeroutput> creates the necessary
|
|
areas required by the particular input methods dictated by the current locale.
|
|
Even if an <computeroutput>XmText[Field]</computeroutput> instance is not
|
|
mapped but just created, VendorShell has the geometry management behavior
|
|
as described previously.</para>
|
|
<para>A <computeroutput>VendorShell</computeroutput> widget does the following:<indexterm>
|
|
<primary>international text input</primary><secondary>VendorShell widget operations</secondary></indexterm></para>
|
|
<itemizedlist remap="Bullet1"><listitem><para>Enables applications to process
|
|
multibyte character input and output that is supported by the locales installed
|
|
in the system.<indexterm><primary>VendorShell widget operations</primary>
|
|
<secondary>processing multibyte character I/O</secondary></indexterm></para>
|
|
</listitem><listitem><para>Manages an input method instance as defined in
|
|
the <computeroutput>XmIm</computeroutput> reference functions.</para>
|
|
</listitem><listitem><para>Supports preediting within a preedit area in either
|
|
OnTheSpot, OffTheSpot, OverTheSpot, Root, or None mode. Localized text can be entered
|
|
into any <computeroutput>Text</computeroutput> child widget in a multiple <computeroutput>Text</computeroutput> children widget tree by changing the focus.</para>
|
|
</listitem><listitem><para>Provides geometry management for descendant child
|
|
widgets.</para>
|
|
</listitem></itemizedlist>
|
|
<note>
|
|
<para>Input method interactions may also be customized by users through a
|
|
dialog box that is invoked from the Style Manager application. Refer to the <emphasis>CDE User's Guide</emphasis> for more information.</para>
|
|
</note>
|
|
<sect2 id="IPG.motif.div.19">
|
|
<title>Geometry Management<indexterm><primary>international text input</primary>
|
|
<secondary>geometry management</secondary></indexterm><indexterm><primary>geometry management</primary><secondary>international text input</secondary>
|
|
</indexterm></title>
|
|
<para>The <computeroutput>VendorShell</computeroutput> widget provides geometry
|
|
management and focus management for the input method's user interface components,
|
|
as necessary. If the locale warrants it (for example, if the locale is a
|
|
Japanese Extended UNIX Code (EUC) locale), the <computeroutput>VendorShell</computeroutput> widget automatically allocates and manages the geometry
|
|
of any required preedit area or status area or both.</para>
|
|
<para>Depending on the current preediting being done, an auxiliary area may
|
|
be required. If so, the <computeroutput>VendorShell</computeroutput> widget
|
|
also instantiates and manages the auxiliary area. Typically, the child of
|
|
the <computeroutput>VendorShell</computeroutput> widget is a container widget
|
|
(such as the <computeroutput>XmBulletinBoard</computeroutput> or <computeroutput>XmRowColumn</computeroutput> widgets) that can manage
|
|
multiple <computeroutput>Text</computeroutput> and <computeroutput>TextField</computeroutput> widgets, which allow multibyte character
|
|
input from the user. In this scenario, all <computeroutput>Text</computeroutput> widgets share the same input method.</para>
|
|
<note>
|
|
<para><indexterm><primary>geometry management</primary><secondary>XmBulletinBoard
|
|
widget</secondary></indexterm><indexterm><primary>geometry management</primary>
|
|
<secondary>XmRowColumn widget</secondary></indexterm><indexterm><primary>geometry management</primary><secondary>Text widget</secondary></indexterm><indexterm>
|
|
<primary>geometry management</primary><secondary>TextField widget</secondary>
|
|
</indexterm><indexterm><primary>international text input</primary><secondary>multibyte characters</secondary></indexterm><indexterm><primary>input method</primary><secondary>Text widget</secondary></indexterm><indexterm><primary>Text widgets, input method</primary></indexterm>The status, preedit, and auxiliary
|
|
areas are not accessible to the application programmer. For example, it is
|
|
not intended for the application programmer to access the window ID of the
|
|
status area. The user does not need to worry about the instantiation or management
|
|
of these components as they are managed as required by the <computeroutput>VendorShell</computeroutput> widget class.</para>
|
|
</note>
|
|
<para>The application programmer has some control over the behavior of the
|
|
input method user interface components through <systemitem>XmNpreeditType</systemitem> resources of the <computeroutput>VendorShell</computeroutput>
|
|
widget class.<indexterm><primary>geometry management</primary><secondary>application programmer controls</secondary></indexterm><indexterm><primary>application programmer, controlling input method components</primary></indexterm>
|
|
(The <literal>OffTheSpot</literal>, <literal>OnTheSpot</literal>, and <literal>OverTheSpot</literal> modes are described elsewhere in this manual).</para>
|
|
<para>Geometry management extends to all input method user interface components.
|
|
When the application program window (a <computeroutput>TopLevelShell</computeroutput>
|
|
widget) is resized, the input method user interface components are resized
|
|
accordingly, and the preedited strings in them are rearranged as required.
|
|
Of course, this assumes that the shell window has a resize policy of True.
|
|
</para>
|
|
<para>When the <computeroutput>VendorShell</computeroutput> widget is created,
|
|
if a specific input method requires a status area, preedit area, or both,
|
|
the size of the VendorShell considers the areas required by these components.
|
|
The extra areas required by the preedit and status areas are part of the <computeroutput>VendorShell</computeroutput> widget's area. They are also
|
|
managed by the <computeroutput>VendorShell</computeroutput> widget, if resizing
|
|
is necessary.</para>
|
|
<para>Because of the potential instantiation of these areas (status and preedit),
|
|
depending on the input method currently being used, the size of the <computeroutput>VendorShell</computeroutput> widget area does not necessarily grow or shrink
|
|
to accommodate exactly the size of its child. The size of the <computeroutput>VendorShell</computeroutput> widget area grows or shrinks to accommodate
|
|
both its child's geometry <emphasis>and</emphasis> the geometry of these
|
|
input method user interface areas. There may be a difference (for example,
|
|
of 20 pixels) in height between the <computeroutput>VendorShell</computeroutput>
|
|
widget and its child widget (the MainWindow area). The width geometry is <symbol role="Variable">not</symbol> affected by the input method user interface
|
|
components.<indexterm><primary>VendorShell widget class</primary><secondary>size</secondary></indexterm><indexterm><primary>VendorShell widget class</primary><secondary>child widget size</secondary></indexterm></para>
|
|
<para>In summary, the requested size of the child is honored if possible;
|
|
the actual size of the <computeroutput>VendorShell</computeroutput> may be
|
|
larger than its child.</para>
|
|
<para>The requests to specify the geometry of the <computeroutput>VendorShell</computeroutput> widget and its child are honored as long as they do not
|
|
conflict with each other or are within the constraint of the <computeroutput>VendorShell</computeroutput> widget's ability to resize. When they do conflict,
|
|
the child's widget geometry request has higher precedence. For example, if
|
|
the size of the child widget is specified as 100x100, the size of VendorShell
|
|
is also specified as 100x100. The resulting VendorShell has a size of 100x120,
|
|
while its child widget gets a size of 100x100. If the size of the child widget
|
|
is not specified, the VendorShell shrinks its child widget if necessary to
|
|
honor its own size specification. For example, if the size of VendorShell
|
|
is specified as 100x100 and no size is specified for its child, the child
|
|
widget has a size of 100x80. If the <computeroutput>VendorShell</computeroutput> widget is disabled from resizing, regardless of what the geometry
|
|
request of its child is, the <computeroutput>VendorShell</computeroutput>
|
|
widget honors only its own geometry specification.</para>
|
|
</sect2>
|
|
<sect2 id="IPG.motif.div.20">
|
|
<title>Focus Management<indexterm><primary>international text input</primary>
|
|
<secondary>focus management</secondary></indexterm><indexterm><primary>VendorShell
|
|
widget class</primary><secondary>focus management</secondary></indexterm><indexterm>
|
|
<primary>focus management</primary><secondary>international text input</secondary>
|
|
</indexterm></title>
|
|
<para>Languages with large numbers of characters (such as Japanese and Chinese)
|
|
require an input method that allows the user to compose characters in that
|
|
language interactively.<indexterm><primary>input method</primary><secondary>multibyte characters</secondary></indexterm> This is because, for these languages,
|
|
there are many more characters than can be reasonably mapped to a terminal
|
|
keyboard.</para>
|
|
<para>The interactive process of composing characters in such languages is
|
|
called <emphasis>preediting</emphasis>. The preediting itself is handled
|
|
by the input method. However, the user interface of the preediting is determined
|
|
by the system environment. An interface needs to exist between the input
|
|
method and the system environment. This is done through the <computeroutput>VendorShell</computeroutput> widget of the system environment.<indexterm>
|
|
<primary>preediting</primary></indexterm><indexterm><primary>VendorShell
|
|
widget class</primary><secondary>as interface</secondary>
|
|
</indexterm><indexterm><primary>interfaces</primary><secondary>between input method and Common Desktop Environment</secondary>
|
|
</indexterm><indexterm><primary>input method</primary><secondary>Common Desktop
|
|
Environment interface</secondary></indexterm><indexterm><primary>Common Desktop
|
|
Environment</primary><secondary>input method interface</secondary></indexterm><indexterm>
|
|
<primary>preediting</primary></indexterm></para>
|
|
<para><!--Original XRef content: 'Figure 4‐3'--><xref role="CodeOrFigureOrTable"
|
|
linkend="IPG.motif.mkr.12"> illustrates a case with Japanese preediting. The
|
|
string shown in reverse video is the string in preediting. This string can
|
|
be moved across different windows by giving focus to the particular window.
|
|
However, only one preediting session can occur at one time.</para>
|
|
<figure>
|
|
<title id="IPG.motif.mkr.12">Japanese preediting example</title>
|
|
<graphic id="IPG.motif.grph.3" entityref="IPG.motif.fig.3"></graphic>
|
|
</figure>
|
|
<para>For an example of focus management, suppose a <computeroutput>TopLevelShell</computeroutput> widget (a subclass of the <computeroutput>VendorShell</computeroutput>
|
|
widget) has an <computeroutput>XmBulletinBoard</computeroutput> widget child
|
|
(MainWindow area), which has five <computeroutput>XmText</computeroutput>
|
|
widgets as children. Assume the locale requires the preedit area, and assume
|
|
the OverTheSpot mode is specified. Because the <computeroutput>VendorShell</computeroutput> widget manages only one instance of an input method, you
|
|
can run only one preedit area at a time inside the <computeroutput>TopLevelShell</computeroutput> widget. If the focus is moved from one <computeroutput>Text</computeroutput> widget to another, the current preedit string under
|
|
construction is also moved on top of the <computeroutput>Text</computeroutput>
|
|
widget that currently has focus. Processing of keys to the old <computeroutput>Text</computeroutput> widget is suspended temporarily. Subsequent interface
|
|
of the input method, such as the delivery of the string at preedit completion,
|
|
is made to the new, focused <computeroutput>Text</computeroutput> widget.<indexterm>
|
|
<primary>focus management</primary><secondary>example description</secondary>
|
|
</indexterm></para>
|
|
<para>The string being preedited can be moved to the location of the focus;
|
|
for example, by clicking the mouse.</para>
|
|
<para>A string that the end user is finished preediting and that is already
|
|
confirmed <emphasis>cannot</emphasis> be reconverted. Once the string is
|
|
composed, it is committed. Refer to Chapter 11 of &MotifProgGd; for information
|
|
on actions that cause a preedit string to be committed.</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="IPG.motif.div.21">
|
|
<title id="IPG.motif.mkr.13">Internationalized User Interface Language<indexterm>
|
|
<primary>National Language Support</primary><secondary>User Interface Language
|
|
(UIL)</secondary></indexterm><indexterm><primary>User Interface Language
|
|
(UIL), see UIL <$nopage></primary>
|
|
</indexterm></title>
|
|
<para>The capability to parse a multibyte character string as a string literal
|
|
has been added to the User Interface Language (UIL).<indexterm><primary>programming for international use</primary><secondary>UIL</secondary><tertiary>parsing multibyte character string</tertiary></indexterm> Creation of a UIL
|
|
file is performed by using the characteristics of the target language and
|
|
writing the User Interface Definition (UID) file.</para>
|
|
<sect2 id="IPG.motif.div.22">
|
|
<title>Programming for Internationalized User Interface Language<indexterm>
|
|
<primary>locales</primary><secondary>UIL compiler</secondary></indexterm></title>
|
|
<para>The UIL compiler parses nonstandard charsets as locale text. This requires
|
|
the UIL compiler to be run in the same locale as any locale text.<indexterm>
|
|
<primary>programming for international use</primary><secondary>UIL</secondary>
|
|
<tertiary>parsing nonstandard charsets</tertiary></indexterm><indexterm>
|
|
<primary>programming for international use</primary><secondary>UIL</secondary>
|
|
<tertiary>locale text</tertiary></indexterm></para>
|
|
<para>If the locale text of a widget requires a font set (more than one font),
|
|
the fonts must be specified within the resource file as a render table.</para>
|
|
<para>To use a specific language with UIL, a UIL file is written according
|
|
to characteristics of the target language and compiled into a UID file. The
|
|
UIL file that contains localized text needs to be compiled in the locale
|
|
in which it is to run.</para>
|
|
<sect3 id="IPG.motif.div.23">
|
|
<title>String Literals<indexterm><primary>programming for international use</primary><secondary>UIL</secondary><tertiary>string literals</tertiary></indexterm><indexterm>
|
|
<primary>string literals</primary><secondary>programming for international
|
|
UIL</secondary></indexterm></title>
|
|
<para>The following shows examples of literal strings. The cur_charset value
|
|
is always set to the default_charset value, which allows the string literal
|
|
to contain locale text.</para>
|
|
<para>To set locale text in the string literal with the default_charset value,
|
|
enter the following:</para>
|
|
<programlisting>XmNlabelString = '<symbol>XXXXXX</symbol>';</programlisting>
|
|
<para>OR</para>
|
|
<programlisting>XmNlabelString = #default_charset“<symbol>XXXXXX</symbol>”;
|
|
</programlisting>
|
|
<para>Compile the UIL file with the <systemitem>LANG</systemitem> environment
|
|
variable matching the encoding of the locale text. Otherwise, the string
|
|
literal is not compiled properly.</para>
|
|
</sect3>
|
|
<sect3 id="IPG.motif.div.24">
|
|
<title>Font<indexterm><primary>font sets</primary><secondary>programming
|
|
for international UIL</secondary></indexterm> Sets<indexterm><primary>programming
|
|
for international use</primary><secondary>UIL</secondary></indexterm><indexterm>
|
|
<primary>programming for international UIL</primary></indexterm><indexterm>
|
|
<primary>font sets</primary><secondary>programming for international UIL</secondary>
|
|
</indexterm></title>
|
|
<para>The font set cannot be set through UIL source programming. Whenever
|
|
the font set is required, you must set it in the resource file as render
|
|
table resource. Refer to &MotifProgGd; for more information.</para>
|
|
</sect3>
|
|
<sect3 id="IPG.motif.div.25">
|
|
<title>Font Lists<indexterm><primary>font lists in UIL, specifying resources
|
|
for</primary></indexterm></title>
|
|
<para>Like font sets, font lists are specified in resource files as render
|
|
tables. Refer to &MotifProgGd; for detailed information.</para>
|
|
</sect3>
|
|
<sect3 id="IPG.motif.div.25a">
|
|
<title>Render Tables<indexterm><primary>render tables in UIL, specifying resources
|
|
for</primary></indexterm></title>
|
|
<para>Render tables, as well as renditions, tab lists,
|
|
and tab stops, are implemented as a special class of objects.
|
|
Refer to &MotifProgGd; for detailed information.</para>
|
|
</sect3>
|
|
<sect3 id="IPG.motif.div.26">
|
|
<title>Creating<indexterm><primary>resource files</primary><secondary>creating
|
|
for international UIL</secondary></indexterm> Resource Files<indexterm><primary>programming for international use</primary><secondary>UIL</secondary></indexterm><indexterm>
|
|
<primary>programming for international UIL</primary></indexterm><indexterm>
|
|
<primary>resource files, creating</primary></indexterm><indexterm><primary>resource files</primary><secondary>creating for international UIL</secondary>
|
|
</indexterm></title>
|
|
<para>If necessary, set the input method-related resources in the resource
|
|
file as shown in the following example:</para>
|
|
<programlisting>*preeditType: OverTheSpot, OnTheSpot, OffTheSpot, Root, or None
|
|
</programlisting>
|
|
</sect3>
|
|
<sect3 id="IPG.motif.div.27">
|
|
<title>Setting the<indexterm><primary>setting the environment</primary><secondary>for international UIL</secondary></indexterm> Environment<indexterm><primary>programming for international use</primary><secondary>UIL</secondary></indexterm><indexterm>
|
|
<primary>programming for international UIL</primary></indexterm><indexterm>
|
|
<primary>setting the environment</primary><secondary>for international UIL</secondary></indexterm></title>
|
|
<para>For a locale-sensitive application, set the UID file to the appropriate
|
|
directory. Set the <systemitem>UIDPATH</systemitem> or <systemitem>XAPPLRESDIR</systemitem> environment variable to the appropriate value.</para>
|
|
<para>For example, to run the <computeroutput>uil_sample</computeroutput>
|
|
program with an English environment (<systemitem>LANG</systemitem> environment
|
|
variable is <computeroutput>en_US</computeroutput>), set <filename>uil_sample.uid</filename> with Latin characters at the <filename>$HOME/en_US</filename>
|
|
directory, or set <filename>uil_sample.uid</filename> to a directory and
|
|
set the <systemitem>UIDPATH</systemitem> environment variable to the full
|
|
path name of the <filename>uil_sample.uid</filename> file.</para>
|
|
<para>To run the <computeroutput>uil_sample</computeroutput> program with
|
|
a Japanese environment (<systemitem>LANG</systemitem> environment variable
|
|
is <systemitem>ja_JP</systemitem>), create a <filename>uil_sample.uid</filename>
|
|
file with Japanese (multibyte) characters at the <filename>$HOME/ja_JP</filename>
|
|
directory, or place <filename>uil_sample.uid</filename> to a unique directory
|
|
and set the <systemitem>UIDPATH</systemitem> environment variable to the
|
|
full path name of the <filename>uil_sample.uid</filename> file. The following
|
|
list specifies the possible variables:</para>
|
|
<informaltable>
|
|
<tgroup cols="2" colsep="0" rowsep="0">
|
|
<colspec align="left" colwidth="100*">
|
|
<colspec align="left" colwidth="356*">
|
|
<tbody>
|
|
<row>
|
|
<entry><para><emphasis>%U</emphasis></para></entry>
|
|
<entry><para>Specifies the UID file string.</para></entry></row>
|
|
<row>
|
|
<entry><para><emphasis>%N</emphasis></para></entry>
|
|
<entry><para>Specifies the class name of the application.</para></entry></row>
|
|
<row>
|
|
<entry><para><emphasis>%L</emphasis></para></entry>
|
|
<entry><para>Specifies the value of the <computeroutput>xnlLanguage</computeroutput>
|
|
resource or <filename>LC_CTYPE</filename> category.</para></entry></row>
|
|
<row>
|
|
<entry><para><emphasis>%l</emphasis></para></entry>
|
|
<entry><para>Specifies the language component of the <computeroutput>xnlLanguage</computeroutput> resource or the <computeroutput>LC_CTYPE</computeroutput>
|
|
category.</para></entry></row></tbody></tgroup></informaltable>
|
|
<para>If the <systemitem>XAPPLRESDIR</systemitem> environment variable is
|
|
set, the <computeroutput>MrmOpenHierarchy()</computeroutput> function searches
|
|
the UID file in the following order:<indexterm><primary>setting the environment</primary><secondary>searching the UID file</secondary></indexterm><indexterm>
|
|
<primary>UID file search</primary></indexterm><indexterm><primary>MrmOpenHierarchy
|
|
function, searching UID file</primary></indexterm><indexterm><primary>UID
|
|
file search</primary></indexterm></para>
|
|
<orderedlist><listitem><para>UID file path name</para>
|
|
</listitem><listitem><para><computeroutput>$UIDPATH</computeroutput></para>
|
|
</listitem><listitem><para>%U</para>
|
|
</listitem><listitem><para><computeroutput>$XAPPLRESDIR/</computeroutput> <emphasis>%L</emphasis><computeroutput>/uid/</computeroutput><emphasis>%N</emphasis> <computeroutput>/</computeroutput><emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>$XAPPLRESDIR/</computeroutput> <emphasis>%l</emphasis><computeroutput>/uid/</computeroutput><emphasis>%N</emphasis> <computeroutput>/</computeroutput><emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>$XAPPLRESDIR/uid/</computeroutput> <emphasis>%N</emphasis><computeroutput>/</computeroutput><emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>$XAPPLRESDIR/</computeroutput> <emphasis>%L</emphasis><computeroutput>/uid/</computeroutput><emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>$XAPPLRESDIR/</computeroutput> <emphasis>%l</emphasis><computeroutput>/uid/</computeroutput><emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>$XAPPLRESDIR/uid/</computeroutput> <emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>$HOME/uid/</computeroutput> <emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>$HOME/</computeroutput> <emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>/usr/lib/X11/</computeroutput> <emphasis>%L</emphasis><computeroutput>/uid/</computeroutput><emphasis>%N</emphasis> <computeroutput>/</computeroutput><emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>/usr/lib/X11/</computeroutput> <emphasis>%l</emphasis><computeroutput>/uid/</computeroutput><emphasis>%N</emphasis> <computeroutput>/</computeroutput><emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>/usr/lib/X11/uid/</computeroutput> <emphasis>%N</emphasis><computeroutput>/</computeroutput><emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>/usr/lib/X11/</computeroutput> <emphasis>%L</emphasis><computeroutput>/uid/</computeroutput><emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>/usr/lib/X11/</computeroutput> <emphasis>%l</emphasis><computeroutput>/uid/</computeroutput><emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>/usr/lib/X11/uid/</computeroutput> <emphasis>%U</emphasis></para>
|
|
</listitem><listitem><para><computeroutput>/usr/include/X11/uid/</computeroutput> <emphasis>%U</emphasis></para>
|
|
</listitem></orderedlist>
|
|
<para>If the <systemitem>XAPPLRESDIR</systemitem> environment variable is
|
|
not set, the <computeroutput>MrmOpenHierarchy()</computeroutput> function
|
|
uses <computeroutput>$HOME</computeroutput> instead of the<systemitem>XAPPLRESDIR</systemitem> environment variable.</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="IPG.motif.div.28">
|
|
<title>default_charset Character Set in UIL<indexterm><primary>User Interface
|
|
Language (UIL), see UIL <$nopage></primary></indexterm><indexterm><primary>default_charset string literal</primary></indexterm><indexterm><primary>string literals</primary><secondary>default_charset in UIL</secondary></indexterm><indexterm><primary>default_charset
|
|
string literal</primary></indexterm></title>
|
|
<para>With the default_charset string literal, any characters can be set as
|
|
a valid string literal. For example, if the <systemitem>LANG</systemitem>
|
|
environment variable is <computeroutput>el_GR</computeroutput>, the string
|
|
literal with default_charset can contain any Greek character. If the <systemitem>LANG</systemitem> environment variable is <computeroutput>ja_JP</computeroutput>,
|
|
the default_charset string literal can contain any Japanese character encoded
|
|
in Japanese EUC.</para>
|
|
<para>If no character set is set to a string literal, the character set of
|
|
the string literal is set as cur_charset. And, in the system environment,
|
|
the cur_charset value is always set as default_charset.</para>
|
|
<sect3 id="IPG.motif.div.29">
|
|
<title>Example<indexterm><primary>UIL (User Interface Language)</primary>
|
|
<secondary>sample Japanese and English program</secondary></indexterm>: uil_sample</title>
|
|
<para><!--Original XRef content: 'Figure 4‐4'--><xref role="CodeOrFigureOrTable"
|
|
linkend="IPG.motif.mkr.14"> shows a UIL sample program on English and Japanese
|
|
environments.</para>
|
|
<figure>
|
|
<title id="IPG.motif.mkr.14">Sample UIL program on English and Japanese environments</title>
|
|
<graphic id="IPG.motif.grph.4" entityref="IPG.motif.fig.4"></graphic>
|
|
</figure>
|
|
<para>In the following sample program, <emphasis>LLL</emphasis> indicates
|
|
locale text, which can be Japanese, Korean, Traditional Chinese, Greek, French,
|
|
or others.</para>
|
|
<programlisting>uil_sample.uil
|
|
!
|
|
! sample uil file - uil_sample.uil
|
|
!
|
|
! C source file - uil_sample.c
|
|
!
|
|
! Resource file - uil-sample.resource
|
|
!
|
|
module Test
|
|
version = 'v1.0'
|
|
names = case_sensitive
|
|
objects = {
|
|
XmPushButton = gadget;
|
|
}
|
|
!************************************
|
|
! declare callback procedure
|
|
!************************************
|
|
procedure
|
|
exit_CB;
|
|
!***************************************************************
|
|
! declare BulletinBoard as parent of PushButton and Text
|
|
!***************************************************************
|
|
object
|
|
bb: XmBulletinBoard {
|
|
arguments{
|
|
XmNwidth = 500;
|
|
XmNheight = 200;
|
|
};
|
|
controls{
|
|
XmPushButton pb1;
|
|
XmText text1;
|
|
};
|
|
};
|
|
!****************************
|
|
! declare PushButton
|
|
!****************************
|
|
object
|
|
pb1: XmPushButton {
|
|
arguments{
|
|
XmNlabelString = #Normal “<emphasis>LLL</emphasis>exit button <emphasis>LLL</emphasis>”;
|
|
XmNx = 50;
|
|
XmNy = 50;
|
|
};
|
|
callbacks{
|
|
XmNactivateCallback = procedure exit_CB;
|
|
};
|
|
};
|
|
!*********************
|
|
! declare Text
|
|
!*********************
|
|
text1: XmText {
|
|
arguments{
|
|
XmNx = 50;
|
|
XmNy = 150;
|
|
};
|
|
};
|
|
end module;
|
|
*
|
|
* C source file - uil_sample.c
|
|
*
|
|
*/
|
|
#include <Mrm/MrmAppl.h>
|
|
#include <locale.h>
|
|
void exit_CB();
|
|
static MrmHierarchy hierarchy;
|
|
static MrmType *class;
|
|
|
|
/******************************************/
|
|
/* specify the UID hierarchy list */
|
|
/*****************************************/
|
|
static char *aray_file[]=
|
|
{“uil_sample.uid”
|
|
};
|
|
static int num_file = (sizeof aray_file / sizeof
|
|
aray_file[0]);
|
|
/******************************************************/
|
|
/* define the mapping between UIL procedure names */
|
|
/* and their addresses */
|
|
|
|
/******************************************************/
|
|
static MRMRegisterArg reglist[]={
|
|
{“exit_CB”,(caddr_t) exit_CB}</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="IPG.motif.div.30">
|
|
<title>Compound Strings in UIL<indexterm><primary>compound strings</primary>
|
|
<secondary>in UIL</secondary></indexterm></title>
|
|
<para>Three mechanisms exist for specifying strings in UIL files:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para>As string literals, which may
|
|
be stored in UID files as either null-terminated strings or compound strings
|
|
</para>
|
|
</listitem><listitem><para>As compound strings</para>
|
|
</listitem><listitem><para>As wide character strings</para>
|
|
</listitem></itemizedlist>
|
|
<para>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.</para>
|
|
<para>Regardless of whether UIL stores string literals in UID files as null-terminated
|
|
strings or as compound<indexterm><primary>string literals</primary><secondary>in UID files</secondary></indexterm> 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:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para>When a string expression consists
|
|
of two or more literals with different character sets or writing directions
|
|
</para>
|
|
</listitem><listitem><para>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)</para>
|
|
</listitem></itemizedlist>
|
|
<para>UIL recognizes a number of keywords specifying character sets. UIL associates
|
|
parsing<indexterm><primary>character set keywords</primary></indexterm><indexterm>
|
|
<primary>character sets, defining with UIL CHARACTER_SET function</primary>
|
|
</indexterm><indexterm><primary>string literals</primary><secondary>syntax</secondary></indexterm> 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 <command>CHARACTER_SET</command> function.
|
|
</para>
|
|
<para>The syntax of a string literal is one of the following:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para>'[<symbol role="Variable">character_string</symbol>]'</para>
|
|
</listitem><listitem><para>[#<symbol role="Variable">char_set</symbol>]</para>
|
|
</listitem><listitem><para>“[<symbol role="Variable">character_string</symbol>]”</para>
|
|
</listitem></itemizedlist>
|
|
<para>For each syntax, the character set of the string is determined as follows:
|
|
</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para>For a string declared as ' <symbol>character_string</symbol>', the character set is the code set component of
|
|
the <systemitem>LANG</systemitem> environment variable, if it is set in the
|
|
UIL compilation environment; or it is the value of <computeroutput>XmFALLBACK_CHARSET</computeroutput> if the <systemitem>LANG</systemitem> environment variable
|
|
is not set or has no code set. By default, the value of <computeroutput>XmFALLBACK_CHARSET</computeroutput> is ISO8859-1, but vendors may supply
|
|
different values.</para>
|
|
</listitem><listitem><para>For a string declared as <literal>#</literal><symbol role="Variable">char_set</symbol> <literal>“</literal> <symbol role="Variable">string</symbol><literal>”</literal>, the character set is <symbol role="Variable">char_set</symbol>.</para>
|
|
</listitem><listitem><para>For a string declared as <literal>“</literal><symbol role="Variable">character</symbol><literal>_</literal> <symbol role="Variable">string</symbol><literal>”</literal>, the character set depends on whether
|
|
the module has a <filename>CHARACTER_SET</filename> clause and whether the
|
|
UIL compiler's <filename>use_setlocale_flag</filename> is set.</para>
|
|
<itemizedlist remap="Bullet2"><listitem><para>If the module has a <filename>CHARACTER_SET</filename> clause, the character set is the one specified in
|
|
that clause.</para>
|
|
</listitem><listitem><para>If the module has no <filename>CHARACTER_SET</filename>
|
|
clause but the <command>uil</command> command was started with the <computeroutput>-s</computeroutput> option, or if the <filename>Uil()</filename> function
|
|
was started with <command>use_setlocale_flag set</command>, UIL calls the <filename>setlocale()</filename> function and parses the string
|
|
in the current locale. The character set of the resulting string is <computeroutput>XmFONTLIST_DEFAULT_TAG</computeroutput>.</para>
|
|
</listitem><listitem><para>If the module has no <filename>CHARACTER_SET</filename>
|
|
clause and the <computeroutput>uil</computeroutput> command was started without
|
|
the <computeroutput>-s</computeroutput> option, or if the <filename>Uil()</filename> function was started without <filename>use_setlocale_flag</filename>, the character set is the code set component of the <systemitem>LANG</systemitem> environment variable, if it is set in the UIL compilation
|
|
environment, or the character set is the value of <computeroutput>XmFALLBACK_CHARSET</computeroutput> if <systemitem>LANG</systemitem> is not set or has no code
|
|
set.</para>
|
|
</listitem></itemizedlist>
|
|
</listitem></itemizedlist>
|
|
<para>UIL always stores a string specified using the <computeroutput>COMPOUND_STRING</computeroutput> function as a compound string. This function takes as arguments
|
|
a string expression and optional specifications of a character set, direction,
|
|
and whether to append a separator to the string. If no character set or direction
|
|
is specified, UIL derives it from the string expression, as described in
|
|
the preceding section.</para>
|
|
<note>
|
|
<para>Certain predefined escape sequences, beginning with a \ (backslash),
|
|
may be displayed in string literals, with the following exceptions: –
|
|
A string in single quotation marks can span multiple lines, with each
|
|
new line character escaped by a backslash. A string in double quotation
|
|
marks cannot span multiple lines. – Escape sequences are processed
|
|
literally inside a string that is parsed in the current locale (a localized
|
|
string).</para>
|
|
</note>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:19:51-->
|