Using callbacks

Edit online

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:

  • Text drawing

    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
  • Indicator (status)

    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
  • Auxiliary

    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:

    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 IMAuxInfo structure defines the dialog needed by the IMED.

    The contents of the auxiliary area are defined by the IMAuxInfo structure, found in the /usr/include/im.h library.

    Subroutine contents Description
    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.
    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 theIMIoctl 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.