Applications that use input methods should provide callback functions so that the Input Method Editor (IMED) can communicate with the user. The type of input method you use determines whether or not callbacks are necessary. For example, the single-byte input method does not need callbacks, but the Japanese input method uses them extensively with the pre-edit facility. Pre-editing allows processing of characters before they are committed to the application.
When you use an input method, only the application can insert or delete pre-edit data and scroll the text. Consequently, the echo of the keystrokes is achieved by the application at the request of the input method logic through callbacks.
When you enter a keystroke, the application calls the IMFilter subroutine. Before returning, the input method can call the echoing callback function for inserting new keystrokes. After a character has been composed, the IMFilter subroutine returns it, and the keystrokes are deleted.
In several cases, the input method logic has to call back the client. Each of these is defined by a callback action. The client specifies which callback should be called for each action.
Types of callbacks are described as follows:
The IMED uses text callbacks to draw any pre-editing text currently being composed. When the callbacks are needed, the application and the IMED share a single-line buffer, where the editing is performed. The IMED also provides cursor information that the callbacks then present to the user.
The text callbacks are as follows:
IMTextDraw Asks the application program to draw the text string IMTextHide Tells the application program to hide the text area IMTextStart Notifies the application program of the length of the pre-editing space IMTextCursor Asks the application program to move the text cursor
The IMED uses indicator callbacks to request internal status. The IMIoctl subroutine works with the IMQueryIndicatorString command to retrieve the text string that provides the internal status. Indicator callbacks are similar to text callbacks, except that instead of sharing a single-line buffer, a status value is used.
The indicator callbacks are as follows:
IMIndicatorDraw Tells the application program to draw the status indicator IMIndicatorHide Tells the application program to hide the status indicator IMBeep Tells the application program to emit a beep sound
The IMED uses auxiliary callbacks to request complex dialogs with the user. Consequently, these callbacks are more sophisticated than text or indicator callbacks.
The auxiliary callbacks are as follows:
The IMAuxInfo structure defines the dialog needed by the IMED.
IMAuxCreate Tells the application program to create an auxiliary area IMAuxDraw Tells the application program to draw an auxiliary area IMAuxHide Tells the application program to hide an auxiliary area IMAuxDestroy Tells the application program to destroy an auxiliary area
The contents of the auxiliary area are defined by the IMAuxInfo structure, found in the /usr/include/im.h library.
The IMAuxInfo structure contains the following fields:
IMTitle Defines the title of the auxiliary area. This is a multibyte string. If title.len is 0, no title displays. IMMessage Defines a list of messages to be presented. From the applications perspective, the IMMessage structure should be treated as informative, output-only text. However, some input methods use the IMMessage structure to conduct a dialog with the user in which the key events received by way of the IMFilter or IMLookupString subroutine are treated as input to the input method. In such cases, the input method may treat the IMMessage structure as either a selectable list or a prompt area. In either case, the application displays only the message contents. The IMProcessAuxiliary subroutine need not be called if the IMSelection structure contains no IMPanel structures and the IMButton field is null.
The message.nline indicates the number of messages contained in the IMMessage structure. Each message is assumed to be a single line. Control characters, such as \t, are not recognized. The text of each message is defined by the IMSTRATT structure, which consists of both a multibyte string and an attribute string. Each attribute is mapped one-to-one for each byte in the text string.
If message.cursor is True, then the IMMessage structure defines a text cursor at location message.cur_row, message.cur_col. The message.cur_col field is defined in terms of bytes. The message.maxwidth field contains the maximum width of all text messages defined in terms of columns.
IMButton Indicates the possible buttons that can be presented to a user. The IMButton field tells the application which user interface controls should be provided for the end user. The button member is of type int and may contain the following masks:
- IM_OK
- Present the OK button.
- IM_CANCEL
- Present the CANCEL button.
- IM_ENTER
- Present the ENTER button.
- IM_RETRY
- Present the RETRY button.
- IM_ABORT
- Present the ABORT button.
- IM_YES
- Present the YES button.
- IM_NO
- Present the NO button.
- IM_HELP
- Present the HELP button.
- IM_PREV
- Present the PREV button.
- IM_NEXT
- Present the NEXT button.
The application should use the IMProcessAuxiliary subroutine to communicate the button selection.
IMSelection Defines a list of items, such as ideographs, that an end user can select. This structure is used when the input method wants to display a large number of items but does not want to control how the list is presented to the user. The IMSelection structure is defined as a list of IMPanel structures. Not all applications support IMSelection structures inside the IMAuxInfo structure. Applications that do support IMSelection structures should perform the IM_SupportSelection operation using the IMIoctl subroutine immediately after creation of the IMObject. In addition, not all applications support multiple IMPanel structures. Therefore, the panel_row and panel_col fields are restricted to a setting of 1 by all input methods.
Each IMPanel structure consists of a list of IMItem fields that should be treated as a two-dimensional, row/column list whose dimensions are defined as item_row times item_col. If item_col is 1, there is only one column. The size of the IMPanel structure is defined in terms of bytes. Each item within the IMPanel structure is less than or equal to panel->maxwidth.
The application should use the IMProcessAuxiliary subroutine to communicate one or more user selections. The IM_SELECTED value indicates which item is selected. The IM_CANCEL value indicates that the user wants to terminate the auxiliary dialog.
hint Used by the input method to provide information about the context of the IMAuxInfo structure. A value of IM_AtTheEvent indicates that the IMAuxInfo structure is associated with the last event passed to the input method by either the IMFilter or IMLookupString subroutine. Other hints are used to distinguish when multiple IMAuxInfo structures are being displayed. status Used by the input method for internal processing. This field should not be used by applications. Each IMAuxInfo structure is independent of the others. The method used for displaying the members is determined by the caller of the input method. The IMAuxInfo structure is used by the IMAuxDraw callback.
All callbacks must be identified when you call the IMCreate subroutine. The IMCallback structure contains the address for each callback function. The caller of the IMCreate subroutine must initialize the IMCallback structure with the addresses.
The callback functions can be called before the IMCreate subroutine returns control to the caller. Usually, the IMTextStart callback is called to identify the size of the pre-edit buffer.