Appendix A. Bidirectional Support in Xm (Motif 1.2) Library

Library Name

/usr/lib/libXm.a

Purpose

The Motif Toolkit is a library that defines a set of widgets with their corresponding functions. The Bidirectional Motif toolkit provides a convenient way of creating Arabic/Hebrew graphical user interfaces.

Description

The additions in libXm.a for Arabic/Hebrew fall into two categories. There are changes which deal with the reserved geometry (right-to-left screen orientation). These affect a large number of widgets and gadgets. Whereas other changes deal with inputting bilingual text and supporting bidirectional functionality (that is, character shaping, symmetric swapping, etc.). The later changes affect mostly Text widgets.

Since the additions in libXm.a for Arabic/Hebrew fall into two categories, a number of additional resources were incorporated in the toolkit. In the following section is a description of these resources, their names and their possible values.

Bidirectional Resources

These resources control the geometry of the screen as well as the bidi behavior of widgets. These can be set, like other resources, either from a resource file or from inside a program (the XtSetArg function). Depending on the way you choose to set them, the way their names and values are written will vary accordingly.

Refer to the Layout Services in the libi18n.a file for more information on these values.

If the resources are set from a resource file:

If the resources are set through the widget's argument list (using the XtSetArg function):

Note: Take care that another resource not related to the added Arabic/Hebrew support still needs to be set, namely the fontList resource. The font list must include an Arabic/Hebrew font name so that Arabic/Hebrew characters can be created.

Example

The following example creates a text widget after setting the layout direction right-to-left and the text mode to implicit. This can be done either from a resource file:

*XmText*layoutDirection :right_to_left
*XmText*textMode :text_mode_implicit

Or, from inside a program:

ArgList args;
XtSetArg(args&1brk.0&rbrk., XmNlayoutDirection, XmRIGHT_TO_LEFT)
XtSetArg(args&1brk.1&rbrk., XmNtextMode, XmTEXT_MODE_IMPLICIT);
XmCreateTextWidget(parent_widget, text_widget_name, args, 2);

The Text Widget

The XmText widget class is affected by all the bidi resources discussed previously. It can display text in three modes: implicit, explicit and visual. It supports character and numeric shaping in addition to a couple of miscellaneous functions: symmetric swapping and the special handling of the seen family. Furthermore, the text widget supports bidi key combinations, these are the same as the ones used by the aixterm Command. The XmText widget also reacts to the layoutDirection resource. See the following section entitled: "Effect of LayoutDirection on Motif Widgets and Gadgets."

The Text Field Widget

The XmTextField widget is affected by all the bidi resources. It behaves like the text widget but it does not handle the explicit text mode.

The Label and Gadget Widget

The XmLabel and XmGadget widget class is affected by the textMode resource in addition to the Primitive (or layoutDirection) resource. See the following section entitled: "Effect of LayoutDirection on Motif Widgets and Gadgets." Setting Implicit Control Support (ICS) and automatic shaping of the label string overrides the default resource to implicit text mode. Otherwise, the label string displays in regular motif behavior.

The List Widget

The XmList widget class is also affected by the textMode resource in addition to the layoutDirection or Primitive resource like the XmLabel widget class. Once the text mode is set to implicit, the Transformation mechanism applies to the list widget. Otherwise, the list item string displays in regular motif behavior.

Effect of Layout Direction on Motif Widgets and Gadgets

The layoutDirection resource in the primitive widget affects the following Motif widgets and Gadgets to enable the bidirectional layout:

Example of Localizing a Motif Application for Bidirectional Support

This section provides an example of how to localize the xmeditor file in /usr/sample for Hebrew and Arabic. The Arabic locales are ar_AA and Ar_AA. The Hebrew locales are Iw_IL and iw_IL.

A translated version of the xmeditor file is also supplied. You can compare your changed version of the file to the translated version.

Enter the following command to make sure that the Arabic/Hebrew locales are installed:

LANG=iw_IL locale

If the categories are not set, the locale may not be installed. Use the SMIT Manage Language Environment menu to install the locales.

Setting the Locale and Changing Geometry

1. Add the following to the xmeditor.c file:

   #include <local.h>

setlocale(LC_ALL , "");

1. Compile the xmeditor file.
2. Add the following line to your .Xdefaults file to work with Arabic in a LeftToRight geometry (LTR):

   fontList:  -dt-interface 
   system-medium-r-normal-L*-*-*-*-*-*-*:

3. Enter the following command to run the xmeditor:

   LANG=ar_AA/./xmeditor

4. When the xmeditor opens, the keyboard is in the Latin layer. Go to the first text field and try the following:
   1. Press Alt+RightShift and enter data. The keyboard switches to the Arabic/Hebrew layer.
   2. Press Alt+Enter. The whole text widget is toggled and the cursor movements are reversed. The keyboard automatically switches to the appropriate layer.
   3. Press Alt+LeftShift and enter data. The data is entered in English.
5. Add the following line to your .Xdefaults file to change to global RightToLeft (RTL) geometry, and run the xmeditor in a Hebrew or Arabic locale:

   :wn' and 

layoutDirection:  right_to_left

The whole layout directionality of the xmeditor is reversed and the Latin strings are also reversed. Cascading pop-ups also work from right to left. All text fields open right to left and cursor movement is opposite from the way it is in Latin.

1. Numeric swapping is automatically turned on. To turn it off and always see digits in Arabic (Latin) form set, enter the following:

   *nssMode: nss_mode_arabic

Translating Hard Coded Strings from Latin to Hebrew or Arabic

This example describes how to translate the File string in the Main Menu. However, you can use the same process to translate all xmeditor strings.

In this example, the strings are hard coded. However, in many applications the strings you need to translate are in separate files which often allows you to test without recompiling anything.

1. Use one of the following commands to open a Hebrew or Arabic aixterm window:
   • For Arabic enter: LANG=ar_AA aixterm
   • For Hebrew enter: LANG=iw_IL aixterm
2. Use the following steps to edit the xmeditor.c file:
   1. Go to the File string location.
   2. In an LTR screen, replace the string by entering data in Hebrew or Arabic. To enter data, press Alt+RightShift and enter the text.
   3. As you type, your text should display with all of the characters in the correct sequence.
3. Compile the xmeditor file and test it. Your layoutDirection can be either left_to_right or right_to_left. You should be able to see the strings as you enter them using either layout.

Translating External Files for BIDI Text

This section describes how to translate files that are external to the application. This example describes how to translate an external file with the following three names:

FILE
HELP
MENU

The output of this file as a translated flat file will be in Hebrew or Arabic, where the lower case characters represent Hebrew/Arabic characters:

file
help
menu

This is how you see the file if you open an En_US aixterm with a Hebrew or Arabic font.

If you open an Arabic or Hebrew aixterm with Arabic or Hebrew font in Implicit mode, the file will display as follows:

elif
pleh
unem

You can read the strings in the correct order.

If you use an Arabic or Hebrew aixterm to translate the original file, then what you have originally is:

FILE
HELP
MENU

Now you will start to translate the word FILE. Remove FILE and enter elif by pressing f , then i , then l , then e , which is the correct order of the word in Hebrew or Arabic.

The result will be in what we see in the Hebrew or Arabic aixterm as follows:

elif
HELP
MENU

If you display the string as a flat file from an En_US aixterm, the file will display in the correct logical character order as follows:

file
HELP
MENU

The shaping in Arabic is done automatically in the Arabic aixterm and in the Arabic Motif. When you translate using it, it also shapes the characters for Arabic.