Common Desktop Environment: Internationalization Programmer's Guide

Inputting Localized Text

Input for localized text is typically done by using either the local input method or the network-based input method.

The local input method means that the input method is built in the Xlib. It is typically used for a language that can be composed using simple rules and that does not require language-specific features. The network-based input method means that the actual input method is provided as separate servers, and Xlib communicates with them through the XIM protocol to do the language-specific composition.

Basic Prompts and Dialogs

It is strongly recommended that applications use the Text widget to do all text input.

Input within a DrawingArea Widget

Many applications do their own drawing within a widget based on input. To provide consistency within the desktop environment, XmIm functions are recommended because the style and geometry management needed for an input method is managed by the VendorShell widget class. The application need only worry about handling key events, focus, and communicating the current input location within the drawing area. Using these functions requires some basic knowledge of the underlying Xlib input method architecture, but a developer need only be concerned with the XmIm pieces of information.

Application-Specific and Language-Specific Intermediate Feedbacks

Some applications may need to directly display intermediate feedback during preediting, such as when an application exceeds the functions supplied by Xlib. Examples of this include for PostScript^TM rendering or using vertical writing.

The core Xlib provides the common set of interfaces that allow an application to display intermediate feedback during preediting. By registering the application's callbacks and setting the preediting style to XNPreeditCallbacks, an application can get the intermediate preediting data from the input method and can draw whatever it needs.

Applications intended to do sophisticated language processing may recognize extensions within a specific XIM implementation and its input method engines. Such applications are on the leading edge and will require familiarity with details of the XIM functions.

Text and TextField Widget

For basic prompts and dialogs, the Text or TextField widget is recommended. Besides resources, all of the XmTextField and XmText functions are available for getting and for setting localized text inside a Text[Field] widget.

Most XmText functions are based on the number of characters, not on the number of bytes. For example, all XmTextPosition() function positions are character positions, not byte positions. The XmTextGetMaxLength() function returns the number of bytes. When in doubt, remember that positions are always in character units.

The width of a Text or TextField widget is determined by the resource value of XmNcolumns. But, this value means the number of the widest characters in the font set, not the number of bytes or columns. For example, suppose that you have selected a variable-width font for the Text widget. The character i may have a width of 1 pixel, while the character W may have a width of 7 pixels. When a value of 10 is set for XmNcolumns, this is considered a request to make the Text widget wide enough to be able to display at least 10 characters. So the Text widget must use the width of the widest character to determine the pixel width of its core widget. With this example, it may be able to display 10 W characters in the widget, or 70 i characters. This structure for XmNcolumns may cause problems in locales whose code set is a multibyte and a multicolumn encoding. As such, this value should be set within a localized resource.

The following section identifies the set of functions available for applications that are used to manage input methods. For applications that use the Text and TextField widgets, refer to "Input Method (Keyboards)".

Character Input within Customized Widgets Not Using Text[Field] Widgets

In some cases, an application may obtain character input from the user but does not use a TextField or Text widget to do so. For example, an application using a DrawingArea widget may allow the user to type in text directly into the DrawingArea. In this case, the application could use the Xlib XIM functions as described in later sections, or alternatively, the application may use the XmIm functions of Motif 1.2. The XmIm functions allow an application to connect to and interact with an input method with a minimum of code. Further, it allows the Motif VendorShell widget to take care of geometry management for the input method on the application's behalf.

Although the XmIm functions are shipped in all implementations of Motif 1.2, the functions are not documented in Motif 1.2. OSF has announced its intention to augment and document the XmIm functions for Motif 2.0. The functions described here are the Motif 1.2 XmIm functions.

Note -

The Motif 1.2 XmIm functions do not support preedit callback style or status callback style input methods. The preedit callback can be used by the Xlib API. For more information, see "XIM Management".

Following are the XmIm functions you can safely use in a Motif 1.2-based application. The formal description of the parameters and types can be found in the Xm.h header file.

Function Name	Description
`XmImRegister()`	Performs `XOpenIM()` and queries the input method for supported styles.
`XmImSetValues()`	Negotiates and selects the preedit and status styles.
`XmImSetFocusValues()`	Creates the XIC, if one does not exist. Notifies the input method that the widget has gained the focus. Sets the values passed to the XIC.
`XmImUnsetFocus()`	Notifies the input method that the widget has lost the focus.
`XmImMbLookupString()`	Xm equivalent of `XmbLookupString()`; converts one or more key events into a character. Return value is identical to `XmbLookupString()`.
`XmImUnregister()`	Disconnects the input method and the widget, allowing connection to a new input method. Does not necessarily close the input method (implementation-dependent).

The XmImSetValues() and XmImSetFocusValues() functions allow the application to pass information needed by the input method. It is important for the application to pass all values even though not all values are needed (for each supports preedit and status style). This is because the application can never be sure which style has been selected by the user or the VendorShell widget. Following are the arguments and data types of each value that should be passed in each call to the XmImSet[Focus]Values() function.

Argument Name	Data Type
`XmNbackground`	Pixel
`XmNforeground`	Pixel
`XmNbackgroundPixma`	Pixmap
`XmNspotLocation`	XPoint
`XmNfontList`	Motif fontlist
`XmNlineSpace`	int (pixel height between consecutive baselines)

The XmIm functions are used in the following manner:

Before initializing the toolkit, the application should call XtSetLanguageProc(NULL, NULL, NULL) to initialize the locale.
After creating the widget where character input is desired, the application should call XmImRegister(widget) to open the input method and establish a connection.
After establishing a connection to the input method, the application should pass the initial XIC values to the input method by calling XmImSetValues() and passing all of the values listed above. This function takes an arg_list and a number_args argument. The arglist is loaded by calling XtSetArg().
Add an event handler, through the XtAddEventHandler() function, for the manager widget of the widget obtaining input from the input method. The event handler is for the FocusChangeMask mask. The handler should call XmImSetFocusValues() when gaining focus and should call XmImUnsetFocus() when losing focus. When setting focus for the input method, pass the full set of values listed above.
Add a DestroyCallback for the widget obtaining input from the input method. In the destroy callback, call XmImUnregister() to notify the input method that you are breaking the connection between the widget and the input method.
Use XmImSetValues() to notify the input method any time one or more of the input method values listed above change (for example, spotLocation).

XIM Management

Following are the XIM management functions.

Function Name	Description
`XOpenIM()`	Establishes a connection to an input method.
`XCloseIM()`	Removes a connection to an input method previously established with a call to XOpenIM().
`XGetIMValues()`	Queries the input method for a list of properties. Currently, the only standard argument in Xlib is `XNQueryInputStyle`.
`XDisplayOfIM()`	Returns the display associated with an input method.
`XLocaleOfIM()`	Returns a string identifying the locale of the input method. There are no standard strings; the value returned by this call is implementation-defined.
`XCreateIC()`	Creates an input context. The input context contains both the data required (if any) by an input method and the information required to display that data.
`XDestroyIC()`	Destroys an input context, freeing any associated memory.
`XIMOfIC()`	Returns the input method currently associated with a given input context.
`XSetICValues()`	Passes zero or more values to an input context to control input of character data, or control display of preedit or status information. A table of all valid input context value arguments can be found in the X11R5 specification.
`XGetICValues()`	Queries an input context to get zero or more input context values. A table of all valid input context value arguments can be found in the X11R5 specification.

XIM Event Handling

Following are the XIM event handling functions:

Function Name	Description
`XmbLookupString()`	Converts keypress events into characters.
`XwcLookupString()`	Converts keypress events into wide characters.
`XmbResetIC()`	Resets an input context to its initial state. Any input pending on that context is deleted. Returns the current preedit value as a `char*` string. Depending on the implementation of the input method, the return value may be NULL.
`XwcResetIC()`	Resets an input context to its initial state. Any input pending on that context is deleted. Returns the current preedit value as a `wchar_t*` string.
`XFilterEvent()`	Allows the input method to process any incoming events to the clients before the application processes them.
`XSetICFocus()`	Notifies the input method that the focus window attached to the specified input context has received keyboard focus.
`XUnsetICFocus()`	Notifies the input method that the specified input context has lost the keyboard focus and that no more input is expected on the focus window attached to that context.

XIM Callback

X Input Methods (XIMs) provide three categories of callbacks. One is preedit callbacks, which allow applications to display the intermediate feedbacks during preediting. The second is geometry callbacks, which allow applications and XIM to negotiate the geometry to be used for XIM. The third is status callbacks, which allow applications to display the internal status of XIM.

XIM Preedit Callback: `PreeditStartCallback`

XIM Status Callbacks: StatusStartCallback

XIM Preedit Caret Callbacks: PreeditCaretCallback

XIM Geometry Callbacks: GeometryCallback

XIM Preedit Callback: `PreeditDoneCallback`

XIM Status Callbacks: StatusDoneCallback

XIM Preedit Callback: `PreeditDrawCallback`

XIM Status Callbacks: StatusDrawCallback