
IM-JA v0.9

Botond Botyanszki

    <boti at rocketmail dot com>

   Copyright  2002 - 2003 Botond Botyanszki
     _________________________________________________________

   Table of Contents
   1. Introduction
   2. Getting and installing IM-JA

        2.1. Installing from source

              2.1.1. Canna support
              2.1.2. Wnn support
              2.1.3. Gnome applet
              2.1.4. Configuring GTK

        2.2. RPM
        2.3. Debian
        2.4. Gentoo
        2.5. FreeBSD
        2.6. CVS

   3. Using IM-JA

        3.1. Invoking the IM-JA input module for GTK
        3.2. The XIM server

              3.2.1. Limitations of the XIM implementation

        3.3. Setting your preferences

              3.3.1. Hotkeys
              3.3.2. Preedit Style
              3.3.3. Status Window
              3.3.4. Conversion Engines
              3.3.5. Other

        3.4. Keys and actions

              3.4.1. Configurable Keys
              3.4.2. Non-configurable keys

        3.5. Using the GNOME panel applet

   4. IM-JA and GTK/GNOME Applications

        4.1. Stock GTK input widgets
        4.2. Applications with custom widgets

   5. Troubleshooting
   6. Feedback

        6.1. Contact and support
        6.2. Bugreports

   7. Credits
     _________________________________________________________

1. Introduction

   IM-JA is a Japanese input module for GTK+2. As of v0.9 it also
   has a XIM implementation.

   It supports kanji conversion using either the Canna or the
   (Free)Wnn kanji conversion engine. IM-JA can also do kanji
   character recognition, you can draw kanji into a widget using
   the mouse. This feature is based on the KanjiPad application
   which has been enhanced in IM-JA.

   IM-JA can be easily configured using a GUI tool. Conversion
   hotkeys, status window, preedit text colors, etc. can be all
   customized. An optional applet is also included for the
   gnome-panel which can be used to display and change the input
   method.

   GTK+2 has the advantage that it doesn't require X, so it
   should be possible to use IM-JA on PDAs and frame-buffer
   devices. Also, IM-JA provides the look-and-feel of GTK (and
   thus GNOME) so it is visually consistent with the client
   application unlike input methods (such as kinput2) which are
   based on Xlib.
     _________________________________________________________

2. Getting and installing IM-JA

   Source and binary packages of the latest release are available
   from the project webpage at http://im-ja.sourceforge.net.
     _________________________________________________________

2.1. Installing from source

   If you want to roll your own from a tarball, here is what you
   need to do. The compile/install procedure is the same as with
   most GNU applications:
              % tar zxpvf im-ja-x.x.tar.gz
              %  cd im-ja-x.x
              % ./configure --prefix=/usr --mandir=/usr/share/man --sys
confdir=/etc
              % make
              % make install

   Before you start, you probably need to install some other
   packages to satisfy the dependencies. Requirements are:
   gconf2, libglade, gtk2 (2.2.0). Please note the dependency on
   version 2.2 of the gtk2 library. Unfortunately only the latest
   distro releases have this. It is recommended that you install
   at least version 2.2.2, earlier versions have a few input
   method related bugs.
     _________________________________________________________

2.1.1. Canna support

   For Canna support, you will need to install the canna
   conversion server, the client libraries and development
   packages containing the header files. The development package
   for canna is libcanna1g-dev (or canna-dev) under debian.

   If you don't want Canna support, you should run configure with
   the --disable-canna option. In this case you don't have to
   install the canna packages.
     _________________________________________________________

2.1.2. Wnn support

   For Wnn support, you will need to install the freewnn
   conversion server (the commercial might work as well), the
   client libraries and development packages containing the
   header files. The development package is freewnn-jserver-dev
   (or libwnn-dev) under debian.

   If you don't want Wnn support, you should run configure with
   the --disable-wnn option. In this case you don't have to
   install the Wnn packages.
     _________________________________________________________

2.1.3. Gnome applet

   The gnome applet depends on libpanel-applet2 (2.0.0) and is
   compiled by default just like Wnn and Canna support.

   If you are not running GNOME or simply don't want to compile
   and install the applet then execute configure with the
   --disable-gnome option.
     _________________________________________________________

2.1.4. Configuring GTK

   The gconf schema is installed into /etc/gconf. This directory
   can be exclusively specified with configure's --sysconfdir
   option.

   To enable the module in GTK so that it shows up in the Input
   Methods menu, you need to add something similar (depends on
   your $prefix) to /etc/gtk-2.0/gtk.immodules:
   "/usr/lib/gtk-2.0/2.2.0/immodules/im-ja.so"
   "im-ja" "Japanese" "gtk+" "/usr/share/locale" "ja"

   If you installed the module into the same prefix as gtk is
   installed in, you can update /etc/gtk-2.0/gtk.immodules by
   issuing the command
      % gtk-query-immodules-2.0 > /etc/gtk-2.0/gtk.immodules

   If you installed it someplace else like
   /usr/local/lib/gtk-2.0/2.2.0/immodules then you could do this:
      % gtk-query-immodules-2.0 /usr/local/lib/gtk-2.0/2.2.0/immodules/
im-ja.so >> /etc/gtk-2.0/gtk.immodules

   Some distributions have scripts to automate this procedure
   such as update-gtk-immodules in Debian.
     _________________________________________________________

2.2. RPM

   An all-in-one binary package should be available from the
   project webpage. Binary RPMs can be installed the following
   way:
 % rpm -i im-ja-x.xxx.rpm

   Upgrading from rpm:
 % rpm --upgrade im-ja-x.xxx.rpm

   If the provided RPM package does not install properly on your
   system, you can build a binary rpm from the source tarball:
 % rpm -tb im-ja-x.x.tar.gz

   The rpm package should be created under
   /usr/src/RPM/RPMS/`uname -m`/ See rpm(8) for details.
     _________________________________________________________

2.3. Debian

   Binary packages are available from the project webpage. IM-JA
   is split up into different Debian packages. Depending on your
   kanji conversion engine you may want to install either
   im-ja-all, im-ja-wnn or im-ja-canna. The optional GNOME panel
   applet is in the im-ja-applet package.

   IM-JA is also apt-get-able. Put this into your
   /etc/apt/sources.list:
   deb http://im-ja.sourceforge.net/ ./
   deb-src http://im-ja.sourceforge.net/ ./

   After running apt-get update, you should be able to install
   the IM-JA packages via apt-get.

   Building debian packages from the tarball:
    $ tar zxpvf im-ja-x.x.tar.gz
    $ cd im-ja-x.x
    $ dpkg-buildpackage -rfakeroot

   You should install the created binary packages with dpkg -i.
   An alternative would be to use apt-src to do the build if you
   have added have the deb-src line to /etc/apt/sources.list.
     _________________________________________________________

2.4. Gentoo

   IM-JA is already included in the Gentoo Linux distribution.
   Type emerge im-ja. If the ebuild is outdated, you may want to
   update the version and try building with the latest release.
     _________________________________________________________

2.5. FreeBSD

   IM-JA has been recently added to the FreeBSD Ports Collection.
   See http://www.freshports.org/japanese/im-ja

   You can download, build, and install im-ja with FreeWnn and
   Canna support (including all dependencies) using the Ports
   Collection:
    $ cd /usr/ports/japanese/im-ja
    $ make install

   The following command will download and install the latest
   binary package of im-ja for your FreeBSD version and
   architecture:
    $ pkg_add -r im-ja

   Please see the FreeBSD Handbook
   http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/port
   s.html for complete details.
     _________________________________________________________

2.6. CVS

   If you want the bleeding-edge, try the cvs version. It should
   work better but might contain some incomplete and buggy code
   in addition to the fixes and improvements to the last release.
   To get the cvs version, execute the following:
    $ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/im-ja check
out im-ja
     _________________________________________________________

3. Using IM-JA

3.1. Invoking the IM-JA input module for GTK

   To be able to input Japanese with IM-JA, GTK needs to load the
   input module. To invoke IM-JA, you should select "Japanese"
   from the Input Methods menu. The following actions should
   bring up this menu if the input widget (such as a text entry,
   text area, combo box, etc) has the focus:

     * Right-click on the widget with the mouse.
     * Press Shift-F10
     * Press the Menu key.

   If you want to have IM-JA automatically preloaded when you
   start your application (I'll use gedit in the example) here is
   what you can do:

     * Start your application like this:
         $ GTK_IM_MODULE="im-ja" gedit
       Or export this environment variable somewhere in your rc
       files.
     * If the locale is set to Japanese, im-ja will be
       automatically used. So you can do this too:
         $ LC_ALL="ja_JP" gedit
     * Edit the file /etc/gtk-2.0/gtk.immodules and change the
       "ja" field to "". This means that IM-JA will be used as
       the default input module.
     _________________________________________________________

3.2. The XIM server

   As of v0.9, IM-JA comes with a XIM server (im-ja-xim-server).
   This should be a drop-in replacement for other Japanese XIM
   servers such as kinput2. The XIM server uses the same settings
   (from GConf) as the GTK2 input module does.

   Clients should be able to connect to the xim server if they
   are started from either the same locale as the server was
   started from, e.g.:

$ LC_ALL=en_US.UTF-8 im-ja-xim-server
$ XMODIFIERS=@im=im-ja-xim-server LC_ALL=en_US.UTF-8 your_app

   or if they are started from a Japanese locale, e.g.:
$ LC_ALL=en_US.UTF-8 im-ja-xim-server
$ XMODIFIERS=@im=im-ja-xim-server LC_ALL=ja_JP your_app

   It is better to have the XMODIFIERS environment variable
   exported somewhere, for example in your .bashrc or globally in
   /etc/environment.

   XIM is a complicated protocol defining multiple modes on how
   the client can render the preedit text. The XIM implementation
   of IM-JA supports XIMPreeditCallbacks or XIMPreeditPosition
   for rendering the preedit text.If the preedit is not drawn
   properly in the client's window the built-in preedit window
   can be used.

   The following applications have been tested and are known to
   work with the IM-JA XIM input:

     * GTK2 applications via the XIM input module :-). It is
       still recommended to use the native GTK2 module.
     * OpenOffice.org
     * Emacs (preedit window) and XEmacs
     * GTK1 applications
     * mlterm
     _________________________________________________________

3.2.1. Limitations of the XIM implementation

   XIMPreeditCallbacks and XIMPreeditPosition modes are quite
   different. The former is similar in concept to the GTK2 input
   modules, whre the client application is responsible for
   drawing the preedit text. In this case the XIM server tells
   the client how to draw the preedit but it has no information
   on where it will be placed in the client window, thus
   positioning the candidate window or the status window below
   the preedit string is not possible. In this case IM-JA will
   automatically use the table-style for the candidate window and
   the status window will be attached to the lower-left corner of
   the client window if the status window style is set to "Below
   cursor".

   The XIM implementation doesn't support custom preedit colors
   for the Preedit style, changing this setting will only have
   effect in your native GTK2 input module.

   DISCLAIMER: I know that XIM is outdated technology and it is
   supposed to be replaced by IIIMF but in reality it is not. An
   IIIMF implementation is also planned but until this framework
   is not accepted more widely I don't see any merits. A XIM
   implementation was something that people can quickly switch to
   and use.
     _________________________________________________________

3.3. Setting your preferences

   IM-JA has a GUI tool to configure user preferences
   conveniently. To start it you can

     * type im-ja-conf at the command line
     * right-click on the panel applet and select Preferences
     * bind a hotkey to start im-ja-conf from any application.
       Refer to the Configurable keys section.

   While most GNOME applications react instantly to any changes
   you make, please note that the settings you change with
   im-ja-conf will not be reflected instantly in already running
   applications, except for the GNOME panel applet. You will have
   to restart already running applications. Also don't forget to
   press Apply before closing im-ja-conf if you have changed any
   settings.
     _________________________________________________________

3.3.1. Hotkeys

   Double-clicking on a key entry under the Hotkeys tab in
   im-ja-conf will bring up a dialog box and wait for your
   keypress. Most of the action names are self-explanatory. The
   behaviour of the action keys is described in the Configurable
   keys section.
     _________________________________________________________

3.3.2. Preedit Style

   The input that can be converted by the input module needs to
   be differentiated from the rest of the text for obvious
   reasons. IM-JA uses underline for this like most other
   Japanese input methods do. To indicate that the conversion
   will only occur on a part of the preedit text, highlighting is
   used.

   Both the background and foreground (font color) are
   configurable for the normal and highlighted preedit text.
   Usually, the default should suffice unless you want to make it
   a bit more fancy looking.
     _________________________________________________________

3.3.3. Status Window

   People tend to prefer different positions for the status
   window. You can chose between four different positions in
   IM-JA. Note that the preedit window will always follow the
   cursor, so this setting only affects the status window.

   Below cursor
          With this option the status window will follow the
          cursor as you type. This is the most convenient way for
          some people because it gives feedback about the current
          input mode without having to look away.

          Note: some applications don't pass a proper cursor
          position to IM-JA, so you it's impossible to display
          the status window below the cursor. "Bottom left" is
          used with such apps.

   Window bottom left
          Another common position for the status window is to
          attach it to the bottom left corner of the window.

   Fixed coordinates
          This is handy if you would like to have the status
          window displayed at a fixed position. For example if
          you don't use the GNOME panel (thus you cannot use the
          applet) you can use this option to make the status
          window appear as if it were on the panel.

   Disabled
          Most probably you will use this option if you have the
          GNOME panel applet loaded.

   The Status window label is also fully configurable. You can
   specify a custom string that you want to have displayed in the
   status window for each input mode. The panel applet and the
   preedit window will be displaying the same.
     _________________________________________________________

3.3.4. Conversion Engines

   IM-JA can use both the Canna and (free)Wnn conversion engines
   in addition to the KanjiPad character recognition interface to
   convert your input to kanji. With the Default kanji conversion
   engine radio button you can select either Wnn or Canna.

   If you are not running the Wnn conversion server (jserver) on
   localhost, you can specify the Server address. For Wnn, you
   will also need to specify the Wnnenvrc file if it's located in
   an unusual place. In most cases it should work fine if you
   leave it empty because IM-JA will look for it in the most
   commonly installed places such as /usr/lib/wnn/ja_JP/wnnenvrc
   and /usr/share/wnn/ja_JP/wnnenvrc. If you have trouble using
   Wnn, make sure you supply the full path to your wnnenvrc file.

   KanjiPad is enabled by default. If its default size is not
   adequate for you, you can set a custom window size.
     _________________________________________________________

3.3.5. Other

   Default startup mode
          Here you can set the Default startup mode. If you chose
          hiragana, then you can immediately enter Japanese
          without having to press Shift-Space (or the key you
          configured for hiragana mode).

   Show preedit window by default
          By default, the preedit window is only shown if the
          application doesn't support preedit mode and requests
          IM-JA to do so. Here you can override this behaviour so
          that the preedit window will be always displayed.

   Candidate window style
          You can select either a dropdown menu or a table to be
          used as the candidate window. The latter is similar to
          the candidate window in kinput2.
     _________________________________________________________

3.4. Keys and actions

3.4.1. Configurable Keys

   Double-clicking on a key entry under the Hotkeys tab in
   im-ja-conf will bring up a dialog box and wait for your
   keypress. The behaviour of the action keys described here is
   for the Wnn conversion engine. Though our goal is to make both
   conversion modes act exactly the same, Canna mode might be
   different in some cases. If you have used a kana-kanji
   conversion program before, you should have no problems with
   IM-JA. Most of the action names are self-explanatory, but here
   is the full list of the description of actions you can bind
   key combinations to:

   Start the im-ja configurator
          Pressing the assigned key will start im-ja-conf from
          the application if IM-JA is active.

   Switch to next input mode
          This will cycle through the next modes in the following
          order: Raw mode -> Hiragana -> Katakana -> Half-width
          katakana -> Zenkaku romaji -> Kanjipad

   Switch to previous input mode
          This does the same as the above in reverse order.

   Set raw input mode
          This key will put IM-JA into raw input mode. In this
          mode you can input romaji (hankaku) directly into the
          application without passing it to the kanji conversion
          server.

   Toggle hiragana/raw mode
          The default, used by other input method programs such
          as kinput2, is Shift-Space. If IM-JA is in raw mode,
          pressing this key will change to conversion (hiragana)
          mode. A hiragana "a" on the status window will indicate
          this mode. Your input, in hiragana, will be sent to the
          conversion engine. You can convert your input in this
          mode by pressing the conversion key (space will
          convert, and another custom key can be assigned as
          well). Pressing this key once again (that is, in
          Hiragana mode) will switch back to raw input mode.

   Toggle full/half-width katakana mode
          If in not in full-width katakana mode, pressing this
          key will put IM-JA into full-width katakana input mode.
          If in full-width katakana mode, pressing this key will
          put IM-JA into half-width katakana input mode.

   Toggle half/full-width katakana mode
          If not in half-width katakana mode, pressing this key
          will put IM-JA into half-width katakana input mode. If
          in half-width katakana mode, pressing this key will put
          IM-JA into full-width katakana input mode.

   Toggle Zenkaku/raw mode
          If not in zenkaku romaji (double-width alphanumeric)
          input mode, pressing this key will put IM-JA into
          Zenkaku romaji input mode. If in zenkaku romaji mode,
          pressing this key will put IM-JA into raw input mode.
          The default key for this action is Zenkaku, which is
          only found on Japanese keyboards.

   Toggle kanjipad/raw input mode
          Pressing this key will put IM-JA into KanjiPad mode if
          it's no already in that mode. The KanjiPad widget will
          pop up into which you can draw kanji characters for
          recognition. If the KanjiPad window is already
          displayed, pressing this key will switch back to raw
          input mode.

   Unconvert current bunsetsu
          Bunsetsu is a phrase (one or more kanji characters
          making up a word) in a sentence. The current bunsetsu
          is usually highlighted when made up of kanji
          characters. Pressing this key will unconvert it into
          hiragana. If the bunsetsu is already hiragana it will
          be converted to katakana. The default key for this
          action is Muhenkan, the unconvert key, which is only
          found on Japanese keyboards.

   Convert current bunsetsu
          If the input has not been converted yet, IM-JA will
          convert the whole string. If the current bunsetsu is
          already converted, the next candidate will be
          presented.

   Get previous candidate
          This key will present the previous (kanji) candidate
          for the currently converted bunsetsu. The default key
          for this action is the Up arrow key.

   Get next candidate
          This key will present the previous (kanji) candidate
          for the currently converted bunsetsu. The default key
          for this action is the Down arrow key.

   Show all candidates
          This key will present all the candidates in a popup
          menu for the currently converted or bunsetsu. If the
          string is not converted, it will be converted first.
          You can navigate with the arrow keys and press enter.
          Space will select the next candidate in the menu. You
          can also use the mouse to make your selection. The
          default key for this action is F9.

   Select previous bunsetsu
          This key will jump to the previous bunsetsu in an
          already converted string if there are more of them. The
          default key for this action is the Left arrow key.

   Select next bunsetsu
          This key will jump to the next bunsetsu in an already
          converted string if there are more of them. The default
          key for this action is the Right arrow key.

   Expand current bunsetsu
          This key will expand the current bunsetsu
          (highlighted), that is, the next character to the right
          will be added to the bunsetsu. It is used to correct
          the bunsetsu when the conversion engine incudes
          more/less characters to be converted and you don't get
          the right kanji. The default key combination for this
          action is Shift-Right.

   Shrink current bunsetsu
          This key will shrink the current bunsetsu
          (highlighted), that is, throw the rightmost kana
          outside of the bunsetsu. It is used to correct the
          bunsetsu when the conversion engine incudes more/less
          characters to be converted and you don't get the right
          kanji. The default key combination for this action is
          Shift-Left.

   Toggle preedit window
          The preedit is the underlined text that is converted by
          the conversion server. In the case of GTK input
          modules, the application is responsible for drawing the
          fonts and setting properties such as the highlight of
          the preedit text. Some applications/widgets are unable
          to display it properly, this is when you can use the
          preedit window in an over-the-spot fashion. Properly
          written applications (such as the gnome-terminal) will
          notify IM-JA if they cannot display the preedit, in
          this case the preedit window will pop up automatically.
          If this doesn't happen or just want to invoke the
          preedit window, press this key.

   Commit preedit string
          Some applications grab the Enter key for their own use
          (e.g. Gaim) and don't pass it to the input method, thus
          it is impossible to commit (enter) the preedit string
          into the application. You can configure and additional
          key combination to commit the preedit string that will
          behave like the Enter key.

   Symbol input
          As of version 0.8, IM-JA can do sophisticated symbol
          input such as arrows, greek letters and cjk punctuation
          marks. Since there are just too many characters in
          unicode, symbols are split into groups in IM-JA.

          Pressing this hotkey will pop up a table with the names
          of symbol groups. Clicking on the symbol group will
          bring up the list of symbols from that group. Press Esc
          if you want to cancel the input.

          Please note that most fonts only support a subset if
          the unicode character set, thus you will be likely to
          see squares, or even the wrong charaters, in place of
          some symbols. Another minor incovenience is that both
          WNN and CANNA don't support unicode, so it is not
          possible to pass the symbol input to the conversion
          server. As a result, your preedit will be committed and
          you won't be able to do any conversion on the text that
          you entered prior to the symbol input any more.

   UniCode input
          Pressing this hotkey will pop up a simple entry where
          you can input the unicode character code. The code has
          to be a four digit hexadecimal number. IM-JA will
          notify you if the input was invalid. Press Esc if you
          want to cancel the input.

          Please note that, similarly to Symbol input, it is not
          possible to pass unicode characters to the conversion
          server. As a result, your preedit will be committed and
          you won't be able to do any conversion on the text that
          you entered prior to the unicode input any more.

   JIS Code input
          Pressing this hotkey will pop up a simple entry where
          you can input a four digit JIS Code. IM-JA will notify
          you if the input was invalid. Press Esc if you want to
          cancel the input.

   It is possible to bind keys to directly invoke the Canna and
   Wnn conversion mode so you can switch beetween them on the
   fly. These two actions are not listed in im-ja-conf, you will
   have to use the gconf-editor to configure these under
   /system/im-ja/hotkeys.
     _________________________________________________________

3.4.2. Non-configurable keys

   There are some keys with hardcoded behaviour in IM-JA. These
   are the following:

   Enter
          Commit the preedit string.

   Escape
          Depending on the (conversion) state in which IM-JA is
          in, pressing Escape will have the following effect:

          + If the current bunsetsu is converted then unconvert
            it.
          + If the current bunsetsu is already unconverted, drop
            the whole preedit text.
          + If there is no preedit text then set the input to raw
            mode.

   Space
          This is similar in behaviour to the configurable
          Convert key, except that the Convert key won't display
          the candidate list when you press it multiple times in
          a row. If you press space on an already converted
          bunsetsu, it will present the candidate list.

   Backspace
          Backspace, as expected, will delete a character from
          the left of the cursor if it's not in a converted
          bunsetsu. If it's a converted bunsetsu, Backspace will
          unconvert it first.

   Delete
          Delete is similar to Backspace. It will delete a
          character from the right of the cursor if it's not in a
          converted bunsetsu. If it's a converted bunsetsu, it
          will be unconverted.

   Left, Right arrows
          With the arrow keys, you can move the cursor in an
          unconverted preedit text.
     _________________________________________________________

3.5. Using the GNOME panel applet

   To add the applet to your GNOME panel, right-click on the
   panel, then select "Add to Panel" -> "Utility" -> "im-ja
   applet".

   The IM-JA GNOME panel applet is used to display the status of
   the input mode of the widget in focus. It can be also used to
   change the input mode without having to press any hotkey by
   left-clicking on the applet. This will pop up a menu from
   where you can select the desired input mode.
     _________________________________________________________

4. IM-JA and GTK/GNOME Applications

   Unfortunately CJK input is far from perfect in GTK2 (and other
   Linux applications in general), but it's getting there slowly.
   The biggest drawback is that a lot of western developers are
   not aware of the complications of CJK input and inadvertently
   write code that will not function properly with IM-JA and
   other input modules.

   The most common mistake is when they bind keys to some actions
   in their applications and forget about the fact that the key
   event needs to be processed by the input module first (e.g.,
   gaim, evolution, gnumeric). Due to the input method
   architecture in GTK2, input methods are not the first to
   recieve the key events, thus the situation is different from
   XIM. See http://bugzilla.gnome.org/show_bug.cgi?id=90082

   This can create some additional work for the programmer.
   Unfortunately this problem is not very easy to solve once you
   want to bind additional keys to a widget. If you are a
   programmer and are wondering how to satisfy this, here are
   some solutions:

     * Unfortunately using g_signal_connect("key_press_event")
       seems to be the most trivial to most people when trying to
       bind additional keys to the widget. Though this is very
       simple, there is no real known solution to pass key events
       through the input modules with this approach.
       While it is certainly a lot more work, the only real
       solution seems to be to subclass the widget and use
       GtkBindingSet. See
       http://bugzilla.gnome.org/show_bug.cgi?id=119051
     * It probably won't work in most situations but you could
       connect your keyevent handler with g_signal_connect_after
       to the input widget.
     * This solution accesses an internal field (im_context) of
       the widget, it is not legal code. Also it will create
       problems (mostly with XIM modules) in case the module
       generates key events, thus it will end up in a loop. See
       http://bugzilla.gnome.org/show_bug.cgi?id=119075 You
       should not use this solution, but here it is:
       Filter the keyevent through the input method context and
       only use the keyevent if the input module did not handle
       it (returned FALSE), so you should have something like
       this at the beginning of your event handler:
      if (gtk_im_context_filter_keypress(GTK_TEXT_VIEW(text_view->entry
)->im_context, event) == TRUE) return TRUE;
      else {
         /* process the GtkEventKey here */
      }
     _________________________________________________________

4.1. Stock GTK input widgets

   Input widgets in GTK2 are close to perfect. GtkIMContext
   related bugs are constantly being fixed, though GTK 2.2.2
   still has a few bugs with GtkIMContext and IM-JA

     * The combo entry gets the arrow (up,down) keyevents before
       GtkIMContext does if there are entries already in the
       combo history. So if you wanted to get the next kanji
       candidate in a combo entry, it won't work: the combo entry
       will append its last stored string to the preedit text.
       There is a patch against gtk in IM-JA CVS that fixes this
       and is already fixed in GTK CVS, it will be in 2.2.3.
     * Cursor is invisible inside a highlighted preedit string
       (preedit that has pango attribute for background set) in
       GtkEntry, GtkComboEntry, GtkAdjustment and possibly
       others. This bug doesn't affect GtkTextView (multiline
       text area). So if you have custom colors for the normal
       preedit enabled, you won't see your cursor inside the text
       in those widgets.
     _________________________________________________________

4.2. Applications with custom widgets

   Unfortunately some applications with custom input widgets are
   far from usable with IM-JA and some other GTK input modules.
   The following is a summary about the (proper lack of) support
   for IM-JA by some of the latest and most widely used GTK2
   application.

   gnome-terminal 2.2.2-1
          gnome-terminal (with libvte) doesn't support preedit
          (pango attributes). This is not a bug, but would be
          nice to have implemented. If you are using kinput2 you
          won't see the highlight. Luckily, gnome-terminal
          notifies the input method by calling
          gtk_im_context_set_use_preedit(), so IM-JA will show
          the preedit window and you will be able to properly see
          the text you want to enter.

          You need to start gnome-terminal from a Japanese locale
          to see the text, otherwise you will get mojibake:

 $ LC_ALL="ja_JP" gnome-terminal

          If you have other gnome-terminal instances running from
          a different locale, then you will need to start it with
          the --disable-factory option, otherwise gnome-terminal
          won't be using the ja_JP locale and you will still get
          mojibake.

   evolution 1.4.0-3
          The GtkHTML widget still needs some coding:

   (evolution:21841): gtkhtml-WARNING **: preedit changed callback: imp
lement me

          This only comes from the main edit widget (GtkHTML),
          other entries work ok. There is a patch I wrote
          available from CVS against gtkhtml that enables
          Japanese input. Also starting the preedit window
          manually should help to see the input.

          Also the Esc and possibly other keys are used in the
          evolution composer without taking the input module into
          account, so if you press Esc, evo will ask if you want
          to discard the message instead of unconverting the
          kanji.

   abiword 1.9.0+cvs.2003.05.10-1
          The cursor coordinates aren't passed properly to IM-JA
          so the status widget appears in the upper left corner.
          The preedit doesn't get displayed properly either and I
          get mojibake so it's useless with Japanese.

   mozilla 1.3.1-2 and other apps using gecko (galeon,
          moz-firebird, epiphany, etc)
          For some reason the mozilla developers ripped out the
          "Input Method" menu, if you right-click on an input
          widget, you won't find it there. You can use IM-JA by

          + preloading IM-JA when starting mozilla:
 $ GTK_IM_MODULE="im-ja" mozilla
          + or if you use galeon, you can right-click on the
            addressbar or some other stock GTK input widget and
            select Japanese there.

          Otherwise Japanese input works mostly. Coloring (Pango
          attributes) doesn't work though and the cursor position
          is not passed properly, so you won't have the status
          window below the cursor. As a result, the candidate
          selection window is not in place either.

   gaim 0.64
          Enter key is stolen from the input module, so it's
          impossible to input Japanese with im-ja. Solutions: you
          can configure an additional "Commit preedit" key that
          will behave as Enter. I wrote a patch that fixes gaim
          with IM-JA and kinput2, it's available from CVS.
     _________________________________________________________

5. Troubleshooting

   You can try recompiling IM-JA with debugging enabled:
./configure --enable-debug

   This will make the GTK module and the xim server print lots of
   debugging information which might help you understand what's
   going on.

   If you have any trouble with IM-JA, please contact the mailing
   list.
     _________________________________________________________

6. Feedback

6.1. Contact and support

   If you have any suggestions, wishes, comments or want to
   report a bug or send a patch, please contact the mailing list.
   You can subscribe at
   http://lists.sourceforge.net/lists/listinfo/im-ja-devel. If
   you want to contact me personally, you can reach me at <boti
   at rocketmail dot com>
     _________________________________________________________

6.2. Bugreports

   Before you report a bug, please make sure you are using the
   latest version. Better yet, if you can, please install the CVS
   version.

   If you send bugreports, please include the following
   information also:

     * IM-JA version
     * GTK2 version
     * recompile IM-JA with the --enable-debug option, run your
       application from a terminal and send us the output. This
       option will also add debugging symbols, so you can run gdb
       on the applicaton IM-JA is running in.
     * if relevant, use strace and send us the output.
     * any other info you might think is important.
     _________________________________________________________

7. Credits

   The following people have directly contributed to the
   development of IM-JA:

     * Main developer and project lead: Botond Botyanszki <boti
       at rocketmail dot com>.
     * Canna RK implementation, kanjipad improvements and various
       other fixes: Srin Tuar <srintuar26 at earthlink dot net>
     * Useful patches and suggestions: Vadim Berezniker <vadim at
       berezniker dot com>

   The following people have contributed indirectly to the
   development of IM-JA:

     * Although im-ja has evolved a lot since, it is based on
       im-canna and im-nakai written by Yukihiro Nakai which in
       turn were based on code written by Yusuke Tabata. See
       http://bonobo.gnome.gr.jp/~nakai/immodule/
     * The kanji recognition uses Owen Taylor's Kanjipad which in
       turn is based on code written by several people. See
       http://fishsoup.net/software/kanjipad/
     * Wnnlib was written by Makoto Ishisone, Software Research
       Associates, Inc. and Moribe Hideyuki.
     * The xim server is heavily based on nabi, a Korean XIM
       server written by Choe Hwanjin <krisna at kldp.org>
     * The xim server uses IMdkit, a XIM library written by
       Hidetoshi Tajima.
