Scim Bridge Developer Manual: IMContexts

Up

About this datatype

The IMContext is the data type for input methods. This contains context data of input method, such as focused widgets or current lines. IMContexts behave as interface between the client library of scim-bridge and GUI libraries. Every message from the agent invokes functions of the current IMContext, and GUI events should be treated as events from IMContexts (see the previous section). So basically, all the functions of IMContext is to be implemented by you.

Registering and deregistering it

In allocating and finalizing IMContexts, the client must call scim_bridge_client_register_imcontext and scim_bridge_client_degister_imcontext. See the previous section.

Showing the preedit string

In the embedded preedit mode, preedit related functions are called everytime the agent update the preedit. There are some functions to implement to show it.

- void scim_bridge_client_imcontext_update_preedit (ScimBridgeClientIMContext *imcontext)
  - Update the preedit.
  - All the changes are applied by calling this function.
- void scim_bridge_client_imcontext_set_preedit_shown (ScimBridgeClientIMContext *imcontext, boolean shown)
  - Set the visibility of the preedit.
  - shown stands for the visibility, TRUE to show it.
- void scim_bridge_client_imcontext_set_preedit_string (ScimBridgeClientIMContext *imcontext, const char *string)
  - Set the contents of the preedit.
  - string is the utf8 encoded string for the preedit.
- void scim_bridge_client_imcontext_set_preedit_attributes (ScimBridgeClientIMContext *imcontext, const ScimBridgeAttribute **attributes, int attribute_count)
  - Set the attributes (= appearance) of the preedit.
  - attributes is the array of the attributes for the preedit.
  - attribute_count is the number of the attributes.
- void scim_bridge_client_imcontext_set_preedit_cursor_position (ScimBridgeClientIMContext *imcontext, int cursor_position)
  - Set the caret index in the preedit.
  - cursor_position is the caret index, 0 means that the caret is in the front of the preediting resion.

Commiting a string

Commit functions are called everytime you settle the preedit string.

- void scim_bridge_client_imcontext_set_commit_string (ScimBridgeClientIMContext *imcontext, const char *string)
  - Set the string to commit.
- void scim_bridge_client_imcontext_commit_string (ScimBridgeClientIMContext *imcontext)
  - Commit a string.

Handling key events

When the key is pressed, the client should call scim_bridge_handle_key_event. See the previous section.

There are also forwarding key events from the agent. Please add it into the GUI event queue.

- void scim_bridge_client_imcontext_forward_key_event (const ScimBridgeClientIMContext *imcontext, const ScimBridgeKeyEvent *key_event)
  - A key event is forwarded from the agent.

Example:

    // This function is called when a key event is forwarded from the agent.
    void scim_bridge_client_imcontext_forward_key_event (const ScimBridgeClientIMContext *imcontext, const ScimBridgeKeyEvent *key_event)
    {
        // Translate it into GTK key event.
        GdkEventKey gdk_event;
        scim_bridge_key_event_bridge_to_gdk (&gdk_event, imcontext->client_window, key_event);

        // Then add it into gtk event queue.
        gdk_event_put ((GdkEvent*) &gdk_event);
    }

Handling the focus and the cursor location

The focus information and the cursor locations should be send the agent. Follow the instruction in the previous section.

Processing the surrounding text

There are some IME which use the text around input cursor. The clients should be able to handle at least one paragraph before and after the cursor. This feature is very important for IMEs of some languages. They choose which character to insert following to the characters before and after the insertation position. The following functions are called when manupulation of the surrounding text is required.

- boolean scim_bridge_client_imcontext_get_surrounding_text (ScimBridgeClientIMContext *imcontext, int before_max, int after_max, char **string, int *cursor_position)
  - The surrounding text is required from the agent.
  - Return TRUE if it succeeded to get the surrounding text, otherwise return FALSE.
  - before_max and after_max are the maximum wchars to get before and after the cursor.
  - string is the pointer for the gotten text. You can give it "NULL" if not available.
  - cursor_position is the cursor_position (in wchar) in the gotten text.
- boolean scim_bridge_client_imcontext_delete_surrounding_text (ScimBridgeClientIMContext *imcontext, int offset, intlength)
  - Delete a part of the surrounding text.
  - This function is applied on the surrounding text, which is gotten by the previous call of get_surrounding_text ().
  - Return TRUE if it succeeded to delete that, otherwise return FALSE.
  - offset is the begining offset (in wchar) of the text to delete from the caret.
  - length is the length of the text to remove.
- boolean scim_bridge_client_imcontext_replace_surrounding_text (ScimBridgeClientIMContext *imcontext, int cursor_position, const char *string)
  - Replace the surrounding text.
  - This function is applied on the surrounding text, which is gotten by the previous call of get_surrounding_text ().
  - Return TRUE if it succeeded to replace the surrounding text, otherwise return FALSE.
  - cursor_position is the cursor_position (in wchar) in the new text.
  - string is the new text to set as the surrounding text.

Misc functions

There are some functions you have to implement, but they can be ignored if you doesn't need it. If you wonder how to implement, leave them as dummy (empty) implimentations.

- void scim_bridge_client_imcontext_beep (const ScimBridgeIMContext *imcontext)
  - Make a beep sound.

Copyright (c) 2006 Ryo Dairiki <ryo-dairiki@users.sourceforge.net>