Applications that use input methods should provide callback functions so that the Input Method Editior (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. Once a character has been composed, the IMFilter subroutine returns it, and the key strokes 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 what callback should be called for each action.
There are three types of callbacks:
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.
| 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 tells the internal status. Indicator callbacks are similar to text callbacks, except that instead of sharing a single-line buffer, a status value is used.
| 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 status callbacks.
| 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 six fields.
| IMTitle | Defines the title of the auxiliary area. This is a multibyte string. If title.len is 0, there is no title to be displayed. |
| 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:
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.
National Language Support Overview for Programming.
The IMAuxCreate subroutine, IMAuxDestroy subroutine, IMAuxDraw subroutine, IMAuxHide subroutine, IMBeep subroutine, IMIndicatorDraw subroutine, IMIndicatorHIde subroutine, IMTextCursor subroutine, IMTextDraw subroutine, IMTextHide subroutine, IMTextStart subroutine, IMIoctl subroutine.