How do I integrate IME into my application?

What is IME?

IME (Input Method Editor) is a common way for users to pass complex text to a text-input field.

If you'd like your users to input Chinese, Japanese, or Korean text to your WebView, you should add an IME widget to your application.

Overview of IME Integration

We currently do not provide a universal IME Widget but we do provide several API hooks so that you can implement the widget yourself and pass data/events to the corresponding WebView.

Displaying your IME Widget over a WebView

Since you will be implementing your own IME widget, you will need to know when to show the widget and where to position it over the WebView.

You can be notified of such events via WebViewListener::onUpdateIME, here is the snippet of code that describes that event:

    /**
     * You should handle this message if you are displaying your
     * own IME (input method editor) widget.
     *
     * This event is fired whenever the user does something that may change 
     * the position or visiblity of the IME Widget (for example, deselecting 
     * a textbox, scrolling the page, tabbing to another textbox, or clicking 
     * the submit button). This event is only active when IME is activated
     * (please see WebView::activateIME).
     *
     * @param   caller  The WebView that fired the event.
     *
     * @param   imeState    The action to apply to your IME widget (for
     *                      example, IME_DISABLE, IME_MOVE_WINDOW, and
     *                      IME_COMPLETE_COMPOSITION).
     *
     * @param   caretRect   The current location of the input caret on
     *                      the page. You should generally move your IME
     *                      widget to this location.
     */
    virtual void onUpdateIME(Awesomium::WebView* caller,
                             Awesomium::IMEState imeState,
                             const Awesomium::Rect& caretRect) = 0;

As a rule of thumb, you should usually hide your widget when IME_DISABLE is received, and show/move your widget to the location specified by caretRect for the other 2 event types.

Make sure to call WebView.activateIME(true) at the beginning of your WebView's lifetime to ensure that you will receive this event. Failure to call this method will prevent all IME-related notifications.

Passing IME input to a WebView

Your IME widget will need to pass translated strings and input back to the WebView during runtime. To make this happen, we offer the following three methods in the WebView API:

• WebView::setIMEComposition
• WebView::confirmIMEComposition
• WebView::cancelIMEComposition

While the user is modifying an IME composition, you should call setIMEComposition so the WebView can update the display of the candidate string and the cursor position.

Once the user selects a final IME composition, you should call confirmIMEComposition to confirm the input string.

If the user cancels input, you should call cancelIMEComposition to exit the input mode.

Passing other keyboard events

During regular (non-IME) input mode, users typically pass three different keyboard event-types to each WebView:

• TYPE_KEY_DOWN
• TYPE_KEY_UP
• TYPE_CHAR

When using IME input mode, you will generally pass most keyboard events except TYPE_CHAR because your IME widget will be translating character key-codes instead. This way users will still be able to backspace characters and move the cursor over existing compositions.