1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
<link rel="stylesheet" type="text/css" href="../document.css">
5
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
6
<meta name="author" content="Ryo Dairiki">
7
<title>Scim Bridge: Developer Manual</title>
10
<p class="bullet_in">Scim Bridge Developer Manual: IMContexts</p>
11
<a href="index.html">Up</a>
14
<p class="bullet_in" id="imcontext">About this datatype</p>
15
<p class="description">
16
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 <a href="client.html">the previous section</a>). So basically, all the functions of IMContext is to be implemented by you.
18
<p class="description">
20
<p class="bullet_in" id="register">Registering and deregistering it</p>
21
<p class="description">
22
In allocating and finalizing IMContexts, the client must call <b>scim_bridge_client_register_imcontext</b> and <b>scim_bridge_client_degister_imcontext</b>. See <a href="client.html#register">the previous section</a>.
24
<p class="bullet_in" id="preedit">Showing the preedit string</p>
25
<p class="description">
26
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.
28
<li>void <b>scim_bridge_client_imcontext_update_preedit</b> (ScimBridgeClientIMContext *<i>imcontext</i>)
30
<li>Update the preedit.</li>
31
<li>All the changes are applied by calling this function.</li>
34
<li>void <b>scim_bridge_client_imcontext_set_preedit_shown</b> (ScimBridgeClientIMContext *<i>imcontext</i>, boolean <i>shown</i>)
36
<li>Set the visibility of the preedit.</li>
37
<li><i>shown</i> stands for the visibility, TRUE to show it.</li>
40
<li>void <b>scim_bridge_client_imcontext_set_preedit_string</b> (ScimBridgeClientIMContext *<i>imcontext</i>, const char *<i>string</i>)
42
<li>Set the contents of the preedit.</li>
43
<li><i>string</i> is the utf8 encoded string for the preedit.</li>
46
<li>void <b>scim_bridge_client_imcontext_set_preedit_attributes</b> (ScimBridgeClientIMContext *<i>imcontext</i>, const ScimBridgeAttribute **<i>attributes</i>, int <i>attribute_count</i>)
48
<li>Set the attributes (= appearance) of the preedit.</li>
49
<li><i>attributes</i> is the array of the attributes for the preedit.</li>
50
<li><i>attribute_count</i> is the number of the attributes.</li>
53
<li>void <b>scim_bridge_client_imcontext_set_preedit_cursor_position</b> (ScimBridgeClientIMContext *<i>imcontext</i>, int <i>cursor_position</i>)
55
<li>Set the caret index in the preedit.</li>
56
<li><i>cursor_position</i> is the caret index, 0 means that the caret is in the front of the preediting resion.</li>
61
<p class="bullet_in" id="commit">Commiting a string</p>
62
<p class="description">
63
Commit functions are called everytime you settle the preedit string.
65
<li>void <b>scim_bridge_client_imcontext_set_commit_string</b> (ScimBridgeClientIMContext *<i>imcontext</i>, const char *<i>string</i>)
67
<li>Set the string to commit.</li>
70
<li>void <b>scim_bridge_client_imcontext_commit_string</b> (ScimBridgeClientIMContext *<i>imcontext</i>)
72
<li>Commit a string.</li>
77
<p class="bullet_in" id="key_event">Handling key events</p>
78
<p class="description">
79
When the key is pressed, the client should call <b>scim_bridge_handle_key_event</b>. See <a href="client.html#key_event">the previous section</a>.
81
<p class="description">
82
There are also forwarding key events from the agent. Please add it into the GUI event queue.
84
<li>void <b>scim_bridge_client_imcontext_forward_key_event</b> (const ScimBridgeClientIMContext *<i>imcontext</i>, const ScimBridgeKeyEvent *<i>key_event</i>)
86
<li>A key event is forwarded from the agent.</li>
90
<p class="caption">Example:</p>
92
// This function is called when a key event is forwarded from the agent.
93
void scim_bridge_client_imcontext_forward_key_event (const ScimBridgeClientIMContext *imcontext, const ScimBridgeKeyEvent *key_event)
95
// Translate it into GTK key event.
96
GdkEventKey gdk_event;
97
scim_bridge_key_event_bridge_to_gdk (&gdk_event, imcontext->client_window, key_event);
99
// Then add it into gtk event queue.
100
gdk_event_put ((GdkEvent*) &gdk_event);
104
<p class="bullet_in" id="focus">Handling the focus and the cursor location</p>
105
<p class="description">
106
The focus information and the cursor locations should be send the agent. Follow the instruction in <a href="client.html#focus">the previous section</a>.
108
<p class="bullet_in" id="surrounding">Processing the surrounding text</p>
109
<p class="description">
110
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.
112
<li>boolean <b>scim_bridge_client_imcontext_get_surrounding_text</b> (ScimBridgeClientIMContext *<i>imcontext</i>, int <i>before_max</i>, int <i>after_max</i>, char **<i>string</i>, int *<i>cursor_position</i>)
114
<li>The surrounding text is required from the agent.</li>
115
<li>Return TRUE if it succeeded to get the surrounding text, otherwise return FALSE.</li>
116
<li><i>before_max</i> and <i>after_max</i> are the maximum wchars to get before and after the cursor.</li>
117
<li><i>string</i> is the pointer for the gotten text. You can give it "NULL" if not available.</li>
118
<li><i>cursor_position</i> is the cursor_position (in wchar) in the gotten text.</li>
121
<li>boolean <b>scim_bridge_client_imcontext_delete_surrounding_text</b> (ScimBridgeClientIMContext *<i>imcontext</i>, int <i>offset</i>, int<i>length</i>)
123
<li>Delete a part of the surrounding text.</li>
124
<li>This function is applied on the surrounding text, which is gotten by the previous call of <b>get_surrounding_text</b> ().</li>
125
<li>Return TRUE if it succeeded to delete that, otherwise return FALSE.</li>
126
<li><i>offset</i> is the begining offset (in wchar) of the text to delete from the caret.</li>
127
<li><i>length</i> is the length of the text to remove.</li>
130
<li>boolean <b>scim_bridge_client_imcontext_replace_surrounding_text</b> (ScimBridgeClientIMContext *<i>imcontext</i>, int <i>cursor_position</i>, const char *<i>string</i>)
132
<li>Replace the surrounding text.</li>
133
<li>This function is applied on the surrounding text, which is gotten by the previous call of <b>get_surrounding_text</b> ().</li>
134
<li>Return TRUE if it succeeded to replace the surrounding text, otherwise return FALSE.</li>
135
<li><i>cursor_position</i> is the cursor_position (in wchar) in the new text.</li>
136
<li><i>string</i> is the new text to set as the surrounding text.</li>
141
<p class="bullet_in" id="misc">Misc functions</p>
142
<p class="description">
143
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.
145
<li>void <b>scim_bridge_client_imcontext_beep</b> (const ScimBridgeIMContext *imcontext)
147
<li>Make a beep sound.</li>
154
<p class="copyright">
155
Copyright (c) 2006 Ryo Dairiki <ryo-dairiki@users.sourceforge.net>
added
removed
extras/immodules/doc/developer/imcontext.html
