Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
531 lines (326 sloc) 16.3 KB
uim.el - Emacs uim bridge
Copyright (c) 2005-2012 uim Project http://code.google.com/p/uim/
All rights reserved.
This software is released under the BSD license.
About uim.el
============
uim.el is a bridge software connecting uim and your Emacs.
By introducing uim.el, various IMs become available on your Emacs
through uim.
Supported Emacs
===============
- GNU Emacs 20.x or later
* Tested on 20.7.1, 21.4.1 and 22.1.1.
- XEmacs 21.x
* Tested on 21.4.20 (with sumo and mule-sumo).
NOTE: Older version such as Mule-2.3 and Emacs-19.x are
unsupported.
NOTE: Also, it might works on Emacs-23.x (CVS version).
Quick Start
===========
uim.el is implemented as a minor-mode of Emacs i.e. uim-mode.
You can use uim.el on your Emacs in two ways; use minor-mode directly
or with LEIM.
Both of them require to add some description into your .emacs
or some other file for Emacs customizing. uim.el provides
the same functions whether it's used with LEIM or not.
If you want to switch between IMs provided by uim.el and other IMs
under Emacs frequently, LEIM is a better choice.
If you want to switch between IMs provided by uim.el and others
frequently, LEIM is recommended.
* Settings for direct use of uim-mode
- Example
;; read uim.el
(require 'uim)
;; to load uim.el only when needed, uncomment below
;; and comment out above
;; (autoload 'uim-mode "uim" nil t)
;; key-binding for uim-mode toggle (ex. C-o)
(global-set-key "\C-o" 'uim-mode)
- Explanation
First, load uim.el directly by require function.
(require 'uim)
Or, if you want to load uim.el only when needed, use autoload
function instead of require.
(autoload 'uim-mode "uim" nil t)
Next, define a key-binding of "uim-mode" command to toggle
uim-mode. For example, if you want to use C-o to toggle uim-mode,
write as follows.
(global-set-key "\C-o" 'uim-mode)
* Settings for use with LEIM
First, load uim-leim.el by require function. It registers the
IMs of uim on Emacs to use them under LEIM.
(require 'uim-leim)
In this case, each name of the IMs is translated into a LEIM
style name. The naming rule of LEIM are as follows.
<Emacs-style language name>-<IM name of uim>-uim
For example, if it is uim-anthy, it is registered to LEIM as
"japanese-anthy-uim," since IM name of uim is "anthy" and
the Emacs-style language name of Japanese is "japanese."
To show the names of all available IMs of LEIM, type following
command.
M-x list-input-method
Default IM of LEIM is specified by a value of
default-input-method variable. For example, to specify uim-anthy
as default IM of LEIM, write as follows.
(setq default-input-method "japanese-anthy-uim")
General Customizing
===================
* Specify default IM of uim-mode independently from uim global setting
By default, when uim-mode is enabled, an IM specified by
configuration tools such as uim-pref-gtk is available.
If you want to use a different IM from uim global setting by
default, set its name to uim-default-im-engine value. For example,
to use uim-anthy anyway by default, write as follows.
(setq uim-default-im-engine "anthy")
* Enable inline candidates displaying mode by default
uim.el has a special feature that displaying candidates just below
(or just above) the preedit strings in vertical direction.
This feature is called "inline candidates displaying mode."
While this mode is one of the most important features of uim.el,
it is invalidated because displayed candidates are collapsed
when Emacs is using proportional fonts.
If you are using fixed fonts on Emacs, you should enable this mode.
To enable this by default, write as follows.
(setq uim-candidate-display-inline t)
To enable (or disable) this mode only under specific major-mode,
make uim-candidate-display-inline as buffer-local variable and then
set non-nil (or nil) to it.
For example, to enable inline candidates displaying mode only
under text-mode, write as follows.
(setq uim-candidate-display-inline nil)
(add-hook 'text-mode-hook
(lambda ()
(make-variable-buffer-local 'uim-candidate-display-inline)
(setq uim-candidate-display-inline t)))
* Change appearances of preedit strings and candidates
uim.el uses following faces to decorate preedit strings and
candidates.
- uim-preedit-highlight-face ... highlighted part of preedit string
- uim-separator-face ... separator of preedit string
- uim-candidate-odd-face ... even number candidates
- uim-candidate-even-face ... odd number candidates
- uim-candidate-selected-face ... selected candidate
- uim-candidate-nth-face ... number of selected candidate
If you want to modify each color of these faces, write as follows.
(set-face-foreground 'uim-preedit-highlight-face "white")
(set-face-background 'uim-preedit-highlight-face "blue")
(set-face-foreground 'uim-separator-face "white")
(set-face-foreground 'uim-candidate-odd-face "blue")
(set-face-background 'uim-candidate-odd-face "white")
(set-face-foreground 'uim-candidate-even-face "blue")
(set-face-background 'uim-candidate-even-face "yellow")
(set-face-foreground 'uim-candidate-selected-face "blue")
(set-face-background 'uim-candidate-selected-face "white")
(set-face-foreground 'uim-candidate-nth-face "red")
(set-face-background 'uim-candidate-nth-face "white")
Colors and their names supported by Emacs can be displayed by
using following command.
M-x list-colors-display
NOTE: If you are using autoload function to load uim.el, the above
settings should be written inside of uim-load-hook.
(add-hook 'uim-load-hook
'(lambda ()
(set-face-foreground 'uim-preedit-highlight-face "white")
(set-face-background 'uim-preedit-highlight-face "blue")
...
(set-face-background 'uim-candidate-nth-face "white")
))
* Put fences / frame to preedit strings and candidates
uim.el can draw borders of preedit strings and candidates by
ASCII characters. It's maybe useful when your Emacs or
terminal emulator don't support colored text or underline.
To display fences at both sides of the preedit strings,
write as follows.
(setq-default uim-preedit-display-fences t)
To display frame around the candidates, write as follows.
(setq-default uim-candidate-display-frame t)
* Enable uim.el by default in specific major-mode
To enable uim.el by default in specific major-mode, call uim-mode
function with an argument (1 or larger number) in the hook of
the major-mode.
For example, if you are using uim-mode, write as follows.
(add-hook 'html-mode-hook
'(lambda () (uim-mode 1)))
Or, if you are using LEIM, write as follows.
(add-hook 'html-mode-hook
'(lambda () (toggle-input-method)))
Unusual Customizing
===================
* Change default input modes of IMs
To set default input modes (ex. Hiragana, half-width katakana)
of IMs different from global setting of uim, make a list
of default input modes and set it to uim-default-im-prop.
For example, to change default input modes of Anthy and SKK into
Hiragana mode, write as follows.
(setq uim-default-im-prop
'("action_anthy_hiragana" "action_skk_hiragana"))
Since there are no document which is organizing the names
of such input modes of each IM, you should read scheme files
of uim to obtain them.
Maybe you can find them by grep scheme files but its not a
good idea.
grep -r register-action /usr/share/uim/*.scm
* Change treatment of Escape-key on terminal-mode
To recognize special keys such as function keys and arrow keys
on Emacs in terminal emulator, uim.el doesn't pass single
Escape-key to uim by default. Therefore, to invoke uim function
bound to a Escape-key, you must press Escape-key in two times.
If you dislike this specification, you can invalidate this
setting while preedit strings are displayed by setting
non-nil value to uim-use-single-escape-on-terminal variable.
(setq uim-use-single-escape-on-terminal t)
NOTE: This configuration is unrecommended because it invalidate
not only special keys such as function keys and arrow keys
but key-bindings which use Alt key.
Commands
========
* uim-mode
Toggle uim.el when using uim-mode directly.
* uim-im-switch
Change an IM of current buffer when using uim-mode directly.
After calling this command, available IMs can be shown by typing
tab key.
NOTE: Use set-input-method command instead of this if you are
using LEIM.
* uim-switch-candidate-display-mode
Toggle inline candidates display mode in current buffer.
* uim-reorder-minor-mode-map-alist
Move uim.el's key-map to the head of the minor-mode key-map list.
Details are described in the FAQ section.
* uim-el-version
Show the version number of uim.el.
FAQ
===
Q. After enabling gtags-mode, uim-anthy cannot be toggled.
I'm using Alt+space to toggle uim-anthy.
A. When Emacs is running on a terminal emulator and a minor-mode
which has a key-map for Escape-prefix (ex. gtags-mode) is loaded
after uim.el, such a problem occurs.
This problem can be solved by moving the key-map of uim.el to
the head of minor-mode key-map list after enable the other
minor-mode.
uim-reorder-minor-mode-alist function do this.
For example, if you are starting gtags-mode like this,
(add-hook 'c-mode-common-hook
'(lambda ()
(gtags-mode 1)))
modify it to call uim-reorder-minor-mode-alist after starting
gtags-mode, like this.
(add-hook 'c-mode-common-hook
'(lambda ()
(gtags-mode 1)
(uim-reorder-minor-mode-map-alist)))
Q. When I edit a LaTeX file, the characters are wiggled whenever
uim.el display/erase candidates. What happen?
A. This is caused by the officious behavior of latex-mode of Emacs-22.x
that change the font size of character after "^" and "_" to smaller.
If you cannot ignore this, disable scaling of superscript and
subscript of latex-mode by adding the below into .emacs.
(add-hook 'latex-mode-hook
'(lambda ()
(setq tex-verbatim-face nil)
(defun tex-font-lock-suscript () nil)))
Q. Sometimes, inline candidates displaying mode is suddenly disabled.
Why?
A. Probably, there is an overlay close to the region where uim.el
plans to display candidates.
Because of technical reasons, uim.el cannot display candidates over
the region which has an overlay. If an overlay exists on the region
where uim.el plans to display candidates, inline candidates displaying
mode is temporarily disabled.
For example, flyspell-mode, show-paren-mode and mmm-mode are using
overlay. Also, it's used at the header area of Mew.
Please note that inline candidates displaying mode might be
turned off when you use uim.el with such modes.
Q. Candidates are collapsed when proportional fonts are used on Emacs.
How can I fix it?
A. Sorry, as long as you use proportional fonts, the collapse of
inline-displayed candidates cannot be prevented.
If you want to use proportional fonts anyway, please disable inline
candidates displaying mode, or else settle for the collapse.
Q. When uim.el is enabled, some key-bindings don't operate correctly.
Why?
A. uim.el always grabs all of key inputs and passes them to uim.
Therefore, some key-bindings which are implemented with particular
way might don't operate correctly when uim.el is enabled.
Even though we modified uim.el to support such a key-binding
whenever we find it, some key-bindings which we've never used
might not operate correctly.
If you've found a key-binding doesn't work correctly when
uim.el is enabled, please report it to the bugzilla or the ML.
Q. ***-mode shows strange behavior when being used with uim.el. Why?
A. Some particular modes might show odd behavior when used with
uim.el because of previously described features of it.
If you've found such a mode, please report it to the bugzilla
or the ML.
Q. Sometimes, Emacs lose control suddenly. Few seconds after,
it becomes available again but uim-mode is invalidated.
A. Maybe a back-end program of uim.el (uim-el-agent or
uim-el-helper-agent) has crashed.
If it can reproduce, please report it to the bugzilla or the ML.
Q. I'm using uim-anthy. When the Emacs is running on a terminal
emulator, the segments cannot be shrinked/extended by pressing
shift-left/shift-right. Why?
A. Probably, its caused by one of following three reasons;
1) shift-left/right is defined as a shortcut key of
your window manager or terminal emulator
2) your terminal emulator cannot recognize/process shift-arrow
3) your Emacs cannot understand escape sequences of shift-arrow
passed by the terminal emulator
1) is simple. Just edit configuration of your window manager
or terminal emulator and invalidate such harmful shortcuts.
2) is serious. You must use alternative key bindings to
shrink/extend segment or must switch to other terminal emulator
which supports shift-arrow.
3) can be fixed by adding some settings which are
pairs of escape sequences and corresponding key sequences
into your .emacs.
For example, GNU Emacs can support most of the major terminal
emulators by adding the below settings.
;; xterm, mlterm
(define-key function-key-map [27 79 49 59 50 65] [S-up])
(define-key function-key-map [27 79 49 59 50 66] [S-down])
(define-key function-key-map [27 79 49 59 50 67] [S-right])
(define-key function-key-map [27 79 49 59 50 68] [S-left])
(define-key function-key-map [27 79 49 59 53 65] [C-up])
(define-key function-key-map [27 79 49 59 53 66] [C-down])
(define-key function-key-map [27 79 49 59 53 67] [C-right])
(define-key function-key-map [27 79 49 59 53 68] [C-left])
(define-key function-key-map [27 79 49 59 54 65] [C-S-up])
(define-key function-key-map [27 79 49 59 54 66] [C-S-down])
(define-key function-key-map [27 79 49 59 54 67] [C-S-right])
(define-key function-key-map [27 79 49 59 54 68] [C-S-left])
;; mrxvt
(define-key function-key-map [27 91 49 59 50 65] [S-up])
(define-key function-key-map [27 91 49 59 50 66] [S-down])
(define-key function-key-map [27 91 49 59 50 67] [S-right])
(define-key function-key-map [27 91 49 59 50 68] [S-left])
(define-key function-key-map [27 91 49 59 53 65] [C-up])
(define-key function-key-map [27 91 49 59 53 66] [C-down])
(define-key function-key-map [27 91 49 59 53 67] [C-right])
(define-key function-key-map [27 91 49 59 53 68] [C-left])
(define-key function-key-map [27 91 49 59 54 65] [C-S-up])
(define-key function-key-map [27 91 49 59 54 66] [C-S-down])
(define-key function-key-map [27 91 49 59 54 67] [C-S-right])
(define-key function-key-map [27 91 49 59 54 68] [C-S-left])
;; urxvt
(define-key function-key-map [27 91 97] [S-up])
(define-key function-key-map [27 91 98] [S-down])
(define-key function-key-map [27 91 99] [S-right])
(define-key function-key-map [27 91 100] [S-left])
(define-key function-key-map [27 79 97] [C-up])
(define-key function-key-map [27 79 98] [C-down])
(define-key function-key-map [27 79 99] [C-right])
(define-key function-key-map [27 79 100] [C-left])
Q. I'm using Japanese kana-input mode. Always "ろ" is inserted
whenever I press each of "ー" and "ろ". How can I input "ー"
with "ー" key?
A. Unfortunately, we have no idea.
At least, ELISP program of GNU Emacs cannot distinguish
these two keys. GNU Emacs just recognize that "\" (backslash)
key has been pressed.
Q. uim.el cannot be executed on Emacs that checked out from CVS
server today's morning! Please fix it ASAP!
A. Sorry, currently, we don't support cutting-edge of CVS of Emacs aggressively
since it often contains strange bugs.
Something went wrong with that request. Please try again.