About uim-xim

uim package includes an XIM server named uim-xim.

XIM is a legacy protocol and has many severe restrictions.  However,
there are many software which support only XIM protocol to input text
especially in Japanese.  So, we had written uim-xim as a tentative
tool.

Currently, uim-xim has many defects.  Some of them can be fixed.  But
the real way to go is to discard XIM itself.

* We already have Gtk+ and Qt immodule version of uim.



Main defect of uim-xim

It only supports input method with language whose character is
convertible into the working encoding of client application.  In
short, if the client application (such as OpenOffice.org, tgif...)
is working with ja_JP.eucJP locale, you can use only Japanese input
methods (anthy, prime, skk...).

But if you use these client applications with UTF-8 locale (such as
ja_JP.UTF-8), you can use all the available multi-linguistic input
methods, and switch them dynamically.



How to use uim-xim

(1) Invoke uim-xim.  You can choose startup conversion engine (input
    method) with --engine=ENGINE command line option (replace ENGINE
    with anthy, prime, skk, tcode, tutcode, and so on.  You can get
    list of available engines with invoking uim-xim --list).  Also you
    can specify the default conversion engine with uim-pref tool.

    Unless specifying with above two methods, preferred engine
    corresponding to startup locale of uim-xim is used automatically.

(2) Set XMODIFIERS=@im=uim and run client.

(3) If you want to use candidate helper program other than default
    toolkit one, set UIM_CANDWIN_PROG environmental variable before
    invoking uim-xim.

     sh:  UIM_CANDWIN_PROG=uim-candwin-qt export UIM_CANDWIN_PROG
     csh: setenv UIM_CANDWIN_PROG uim-candwin-qt

    If nothing specified, uim-candwin-gtk or uim-candwin-qt becomes
    default depending on the selected toolkit.  If uim is not
    configured either with GTK+ or Qt, candidate helper is not used.

(4) To change conversion engines dynamically, use uim-im-switcher
    tool.

(5) Most settings of working input contexts are dynamically
    configurable by uim-pref-{gtk,qt}.



How to use extra modifier keys

uim supports 'Super' and 'Hyper' modifier keys for customized key
operations. Try following steps to enable the feature.

(1) map arbitrary keys to Super and Hyper keys
  xmodmap -e 'keycode 115 = Super_L'      # left Windows key
  xmodmap -e 'keycode 116 = Super_R'      # right Windows key
  xmodmap -e 'add mod3 = Super_L Super_R' # any mod number is OK

  xmodmap -e 'keycode 117 = Hyper_L'      # 'Application' key
  xmodmap -e 'add mod4 = Hyper_L'	  # any mod number is OK

(2) define your own key-bindings with uim-pref.



Bypassing uim temporarily

uim has 'emergency key' feature to bypass uim temporarily.  This is
useful with some applications.  Also another way to avoid language
conversion is choosing "direct" input method using uim-im-switcher
tool or IM-toggle facility using keyboard shotcuts.  We recommend
latter method.

* The way to use 'emergency key' 
  (1) Set following environment variable before invoking uim-xim.
      LIBUIM_ENABLE_EMERGENCY_KEY=1

  (2) Press Shift + Backspace to disable/enable uim key
      processing. Key inputs are directly passed to applications while
      uim key processing is disabled by emergency key.



About XIM event flow

uim-xim supports two XIM event flow methods, full-synchronous-method
(like kinput2, skkinput2...) and on-demand-synchronous method (like
XIM server using IMdkit, such as SCIM's x11 frontend).  Default
behavior of uim-xim is set to use full-synchronous-method.  If you get
occasional XIM_ERROR while using some specific XIM client
applications, please try to use on-demand-synchronous method with
adding '--async' command line startup option (Warning:
on-demand-synchronous method is known to not work with current XIM
implementation of Tcl/Tk version 8.{3,4}).



Internal Implementation

uim-xim processes all IM-related strings as UTF-8 for internal
reasons. When a XIM client application runs on an UTF-8 locale such as
ja_JP.UTF-8, the strings are converted as follows.

  * "foo" expresses a string encoded in foo.

uim-anthy (only for example)
   |
   v
"EUC-JP"
   |
   v
libuim (iconv(3))
   |
   v
"UTF-8"
   |
   v
uim-xim (XmbTextListToTextProperty)
   |
   v
"compound text"
   |
   v
XIM client


uim-xim also supports XIM clients working on non UTF-8 native locales
such as ja_JP.eucJP. When a client application runs on such locales,
some additional encoding conversion occurs as follows.

uim-anthy (only for example)
   |
   v
"EUC-JP"
   |
   v
libuim (iconv(3))
   |
   v
"UTF-8"
   |
   v
uim-xim (iconv(3))
   |
   v
"EUC-JP"
   |
   v
uim-xim (XmbTextListToTextProperty)
   |
   v
"compound text"
   |
   v
XIM client


In such case, uim-xim performs an additional conversion via UTF-8 to
process the strings in the implementation. But it is ensured that no
character code alteration will occur since the both 'native->UTF-8"
and 'UTF-8->native' conversions are performed by same converter
iconv(3). This results the string as accurate as the old
implementation which is dedicated to ja_JP.eucJP encoding as follows.

uim-anthy (only for example)
   |
   v
"EUC-JP"
   |
   v
libuim (iconv(3))
   |
   v
"EUC-JP"
   |
   v
uim-xim (XmbTextListToTextProperty)
   |
   v
"compound text"
   |
   v
XIM client
