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.
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. In English, for example, the capital letters are produced by pressing the <Shift> key in combination with a letter key. Other alphabetic languages with larger alphabets than English may use slightly more complex combinations of keystrokes to describe their entire alphabet.
This problem, however, is compounded many times in the case of ideographic languages, which may require thousands of different characters for basic text. This far exceeds the capability of any keyboard and makes it impossible to have a keyboard with all of the language's symbols. An input method can be used to overcome this difficulty.
An input method is simply the mechanism that is used to map between the keys pressed by a user and the resulting characters that are input to an application. A common feature of many input methods is that the application user may press combinations of keys to create a single character. Creating characters from keystrokes is called pre-editing.
Input methods may require several areas to display the actual keystrokes.
Displays the data in an input method window that is placed over the point of insertion.
Displays the pre-edit window inside the application window (usually at the bottom) but not at the point of insertion.
Displays the pre-edit string in the text widget window.
Uses a pre-edit window that is a child of the root window.
A VendorShell resource, XmNpreeditType 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.
Input methods are supplied by vendors and are implementation dependent. The VendorShell resource XmNinputMethod 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.
Figure 8 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.
Figure 8. Text Widget Pre-Edit and Status Areas Using Over-the-Spot.
View figure.
Figure 9 shows the same window after a "u" has been entered following the "H" shown in Figure 8.
Figure 9. Text Widget Pre-Edit Area After Next Character Entry.
View figure.
Here the pre-edit area is displaying the phonetic equivalent of the English letters "hu" in Hiragana.
When on-the-spot input style is used, a pre-edit string is displayed in the
text widget window. This preedit string is considered part of the text widget
value, and its integrity is ensured by the verify callbacks of the text
widget. If the verify callbacks of the text widget do not accept any part of
the preedit buffer, the preedit string is committed. The following actions
also cause the text widget to commit the preedit string before performing the
specified action:
| Commit Actions |
| cut |
| paste |
| selection |
| cursor movement |
| commit key |
| Note: | Note: Cursor movement may be interpreted by the input method as cursor movement within the preedit buffer. If this is the case, the preedit buffer may not be committed. This behavior is completely dependent upon the implementation of the input method. |
In the case of a shared XIC, the widgets that share the XIC shall retain the preedit buffer, if any, and preedit state when focus is switched between the widgets that share the XIC.
When the preedit buffer is active, it may be highlighted. This highlight
value can be set by the input method server. The following mapping table
relates Text widget highlighting modes to the input method highlighting
feedbacks:
| XIMFeedback | XmHighlightMode |
| XIMReverse | XmHIGHLIGHT_SELECTED |
| XIMUnderline | XmHIGHLIGHT_SECONDARY_SELECTED |
| XIMHighlight | XmHIGHLIGHT_NORMAL |
| XIMPrimary | XmHIGHLIGHT_SELECTED |
| XIMSecondary | XmHIGHLIGHT_SECONDARY_SELECTED |
| XIMTertiary | XmHIGHLIGHT_SELECTED |
In normal insertion mode, original data in the text widget is shifted out to give way for the preedit string at the insertion point.
In overstrike mode, the preedit string will replace the same number of characters, if available before the end of the text widget value, at the insertion point during the preedit process.
An input context 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 relationship between the input method and its input contexts is roughly comparable to that between the display and its windows. The following figure shows the relationships involved. The input method is determined by the XmNinputMethod resource of the nearest ancestor VendorShell, or by the locale specified by the application user.
Figure 10. Input Method and Input Contexts.
View figure.
The widgets in the Motif widget set are equipped to choose the appropriate input method based on the specified locale. This process is transparent to the user, as well as to the programmer of most applications. Most programmers will not need any more than to know what to expect under different values of the XmNpreeditType resource. Occasionally, however, a programmer will require direct access to the input method. For example, in order to write a widget that accepts typed input, the input method must be explicitly nominated. Motif makes available a high-level interface to the basic Xlib input method functions.
| Note: | The following XmIm functions are made available only for the convenience of the authors of new widgets. Except for the XmDrawingArea widget, these routines should not be used with existing widgets. |
A widget must be registered with an input method and context before an application can use XmImMbLookupString to retrieve multibyte text from the input method. The XmImRegister function is the usual method for selecting and allocating an input method for a widget. It starts from the given widget, and searches up the widget hierarchy until it finds a shell that has an XmNinputMethod resource. This resource is only defined for the VendorShell widget. If there is an open input method for this display, the current widget will be attached to it. If not, a new input method, specified by the XmNinputMethod resource, will be opened and attached to the XmDisplay. If the XmNinputMethod is NULL, or unspecified, the input method corresponding to the current locale will be chosen and opened. Motif will only support a single input method per application.
XmImRegister and XmImSetValues (or XmImSetFocusValues) do not return the XIM and XIC data structures to the calling application, but maintain the connections between the widget and its input method and input context in an internal registry until XmImUnregister is called. This will then permit the application to use XmImMbLookupString and XmImSetFocus functions, which take the widget as an argument.
The two XmImRegister and XmImUnregister functions, as well as and XmImSetValues (or XmImSetFocusValues), are the only input manager functions needed to establish input methods and contexts for all but the most unusual applications. These are the only calls needed to implement the Motif Text and TextField widgets.
Like the XmImRegister function, the XmImGetXIM function searches from the given widget, up the widget hierarchy, until it finds a shell that has an XmNinputMethod resource. If there is an open input method for the display, it will simply be returned. Otherwise, a new input method is opened, as specified by the XmNinputMethod resource found, and attached to the XmDisplay. If the XmNinputMethod is NULL, or unspecified, the input method corresponding to the current locale will be chosen and opened. Motif will only support a single input method per application. The XmImRegister, XmImUnregister, and XmImSetValues (or XmImSetFocusValues) functions will suffice for most applications. Use XmImGetXIM and XmImCloseXIM when the widget needs a different input policy than its parent, or needs access to the input method data structure.
Use XmImCloseXIM to release the input method associated with the input widget's XmDisplay. The function also frees all the input contexts associated with the input method, and their associated memory, and unregisters all widgets associated with the freed input contexts. To close only the input context for one widget, use XmImUnregister or XmImFreeXIC.
The following functions handle the creation and deletion of an input context.
Use the XmImGetXIC function to create and register a new input context for a widget. A new input context is not required if the current input policy is XmPER_SHELL and an open input policy already exists. In this case, XmImGetXIC registers the input widget with the existing input context, and returns the shared XIC. The XmImSetValues function is equivalent to calling the XmImGetXIC function with a NULL argument list and an input policy of XmINHERIT_POLICY. Unlike XmImRegister, XmImGetXIC returns the created XIC data structure. Use XmImGetXIC to override the default input policy, or to specify new values for input context parameters.
The XmImSetXIC function allows the application to provide other input contexts to use with the widget and to access the current registered input context data structure. The input XIC is registered as the current XIC, and any XIC previously registered with the input widget is removed. The function returns the newly registered XIC. If the input XIC argument is NULL, XmImSetXIC simply returns the currently registered XIC.
The XmImFreeXIC function unregisters all widgets currently registered with a particular input context. It then removes the XIC itself, and frees the memory allocated to it.
These functions may be used to modify an existing input context:
Use XmImSetValues to create an input context, or to modify an existing one. If the current state of the input context does not allow modification, the XIC will be unregistered and deleted, and a new one will be created and registered with the input widget. Also, if there is not yet an XIC for the widget, one will be created using the given parameters.
The XmImSetFocusValues function is nearly identical to the XmImSetValues function, except that, after the input context values have been reset, the input focus window for the XIC is set to the window of the input widget.
Use the XmImUnsetFocus function to unset the focus window for any XIC registered to the input widget. If the focus window is not set, this function has no effect.
The following function is used to receive data from the input context:
The XmImMbLookupString function is the heart of the input method. On input, it accepts a widget and a KeyEvent. Using the input context registered with the given widget, the function returns a buffer of multibyte text, a keysym computed for the event, and the length of the string in the output buffer.
Note that, if the key event did not complete some necessary pre-edit sequence, the length of the returned string may be zero. For example, in Figure 8, the key event that produced the "H" shown, since it does not specify a unique Hiragana character, would produce a zero-length return from XmImMbLookupString. The subsequent key event, shown in Figure 9, produces a "u." XmImMbLookupString can now map the English letters "Hu" to a unique Hiragana character, so that character is returned to the application, presumably to be drawn in some appropriate place.
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 widget's XmNfontList resource and creates the widget as a descendant of VendorShell. 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 VendorShell resource XmNpreeditType 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.
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 the various Motif text widgets, the application must use the XmIm 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.
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 geometry management. If the application uses either XtGetValues or XtSetValues to get or set the height (XmNheight) of VendorShell, 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.
Figure 11. Text Widget Pre-Edit and Status Areas Using Off-the-Spot.
View figure.