Character Input within Customized Widgets Not Using Text[Field] Widgets (Common Desktop Environment: Internationalization Programmer's Guide)

Common Desktop Environment: Internationalization Programmer's Guide

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).