README
1About uim-xim
2
3uim package includes an XIM server named uim-xim.
4
5XIM is a legacy protocol and has many severe restrictions. However,
6there are many software which support only XIM protocol to input text
7especially in Japanese. So, we had written uim-xim as a tentative
8tool.
9
10Currently, uim-xim has many defects. Some of them can be fixed. But
11the real way to go is to discard XIM itself.
12
13* We already have Gtk+ and Qt immodule version of uim.
14
15
16
17Main defect of uim-xim
18
19It only supports input method with language whose character is
20convertible into the working encoding of client application. In
21short, if the client application (such as OpenOffice.org, tgif...)
22is working with ja_JP.eucJP locale, you can use only Japanese input
23methods (anthy, prime, skk...).
24
25But if you use these client applications with UTF-8 locale (such as
26ja_JP.UTF-8), you can use all the available multi-linguistic input
27methods, and switch them dynamically.
28
29
30
31How to use uim-xim
32
33(1) Invoke uim-xim. You can choose startup conversion engine (input
34 method) with --engine=ENGINE command line option (replace ENGINE
35 with anthy, prime, skk, tcode, tutcode, and so on. You can get
36 list of available engines with invoking uim-xim --list). Also you
37 can specify the default conversion engine with uim-pref tool.
38
39 Unless specifying with above two methods, preferred engine
40 corresponding to startup locale of uim-xim is used automatically.
41
42(2) Set XMODIFIERS=@im=uim and run client.
43
44(3) If you want to use candidate helper program other than default
45 toolkit one, set UIM_CANDWIN_PROG environmental variable before
46 invoking uim-xim.
47
48 sh: UIM_CANDWIN_PROG=uim-candwin-qt export UIM_CANDWIN_PROG
49 csh: setenv UIM_CANDWIN_PROG uim-candwin-qt
50
51 If nothing specified, uim-candwin-gtk or uim-candwin-qt becomes
52 default depending on the selected toolkit. If uim is not
53 configured either with GTK+ or Qt, candidate helper is not used.
54
55(4) To change conversion engines dynamically, use uim-im-switcher
56 tool.
57
58(5) Most settings of working input contexts are dynamically
59 configurable by uim-pref-{gtk,qt}.
60
61
62
63How to use extra modifier keys
64
65uim supports 'Super' and 'Hyper' modifier keys for customized key
66operations. Try following steps to enable the feature.
67
68(1) map arbitrary keys to Super and Hyper keys
69 xmodmap -e 'keycode 115 = Super_L' # left Windows key
70 xmodmap -e 'keycode 116 = Super_R' # right Windows key
71 xmodmap -e 'add mod3 = Super_L Super_R' # any mod number is OK
72
73 xmodmap -e 'keycode 117 = Hyper_L' # 'Application' key
74 xmodmap -e 'add mod4 = Hyper_L' # any mod number is OK
75
76(2) define your own key-bindings with uim-pref.
77
78
79
80Bypassing uim temporarily
81
82uim has 'emergency key' feature to bypass uim temporarily. This is
83useful with some applications. Also another way to avoid language
84conversion is choosing "direct" input method using uim-im-switcher
85tool or IM-toggle facility using keyboard shotcuts. We recommend
86latter method.
87
88* The way to use 'emergency key'
89 (1) Set following environment variable before invoking uim-xim.
90 LIBUIM_ENABLE_EMERGENCY_KEY=1
91
92 (2) Press Shift + Backspace to disable/enable uim key
93 processing. Key inputs are directly passed to applications while
94 uim key processing is disabled by emergency key.
95
96
97
98About XIM event flow
99
100uim-xim supports two XIM event flow methods, full-synchronous-method
101(like kinput2, skkinput2...) and on-demand-synchronous method (like
102XIM server using IMdkit, such as SCIM's x11 frontend). Default
103behavior of uim-xim is set to use full-synchronous-method. If you get
104occasional XIM_ERROR while using some specific XIM client
105applications, please try to use on-demand-synchronous method with
106adding '--async' command line startup option (Warning:
107on-demand-synchronous method is known to not work with current XIM
108implementation of Tcl/Tk version 8.{3,4}).
109
110
111
112Internal Implementation
113
114uim-xim processes all IM-related strings as UTF-8 for internal
115reasons. When a XIM client application runs on an UTF-8 locale such as
116ja_JP.UTF-8, the strings are converted as follows.
117
118 * "foo" expresses a string encoded in foo.
119
120uim-anthy (only for example)
121 |
122 v
123"EUC-JP"
124 |
125 v
126libuim (iconv(3))
127 |
128 v
129"UTF-8"
130 |
131 v
132uim-xim (XmbTextListToTextProperty)
133 |
134 v
135"compound text"
136 |
137 v
138XIM client
139
140
141uim-xim also supports XIM clients working on non UTF-8 native locales
142such as ja_JP.eucJP. When a client application runs on such locales,
143some additional encoding conversion occurs as follows.
144
145uim-anthy (only for example)
146 |
147 v
148"EUC-JP"
149 |
150 v
151libuim (iconv(3))
152 |
153 v
154"UTF-8"
155 |
156 v
157uim-xim (iconv(3))
158 |
159 v
160"EUC-JP"
161 |
162 v
163uim-xim (XmbTextListToTextProperty)
164 |
165 v
166"compound text"
167 |
168 v
169XIM client
170
171
172In such case, uim-xim performs an additional conversion via UTF-8 to
173process the strings in the implementation. But it is ensured that no
174character code alteration will occur since the both 'native->UTF-8"
175and 'UTF-8->native' conversions are performed by same converter
176iconv(3). This results the string as accurate as the old
177implementation which is dedicated to ja_JP.eucJP encoding as follows.
178
179uim-anthy (only for example)
180 |
181 v
182"EUC-JP"
183 |
184 v
185libuim (iconv(3))
186 |
187 v
188"EUC-JP"
189 |
190 v
191uim-xim (XmbTextListToTextProperty)
192 |
193 v
194"compound text"
195 |
196 v
197XIM client
198