[[http://melpa.org/#/fcitx][file:http://melpa.org/packages/fcitx-badge.svg]] [[http://stable.melpa.org/#/fcitx][file:http://stable.melpa.org/packages/fcitx-badge.svg]]
Better [[https://github.com/fcitx/fcitx/][fcitx]] integration for Emacs.
[[./README-zh.org][中文版(需要更新）]]
This package provides a set of functions to make fcitx work better in Emacs.
This is originally designed to be used along with =fcitx= on Linux, but it can also be used on other platforms with other input methods.
For OSX users, see [[https://github.com/CodeFalling/fcitx-remote-for-osx][fcitx-remote-for-osx]]
For Windows users, see [[https://github.com/cute-jumper/fcitx-remote-for-windows][fcitx-remote-for-windows]]
For users who want to add support for other input methods, see the following section: Work with Other Input methods
Setup Recommendation: install this package from [[http://melpa.org][melpa]].
Or, if you like to manually install this package: : (add-to-list 'load-path "/path/to/fcitx.el") : (require 'fcitx)
You can choose between two different setup commands: : M-x fcitx-default-setup or : M-x fcitx-aggressive-setup
The differences between these two setups will be explained later.
Example Settings All the examples below use =fcitx-aggressive-setup=.
For Emacs users on Linux: : (fcitx-aggressive-setup) : (setq fcitx-use-dbus t) ;; or set to 'fcitx5 if you use fcitx5
For Emacs users on OS X: : (fcitx-aggressive-setup)
For Spacemacs users: : ;; Make sure the following comes before `(fcitx-aggressive-setup)' : (setq fcitx-active-evil-states '(insert emacs hybrid)) ; if you use hybrid mode : (fcitx-aggressive-setup) : (fcitx-prefix-keys-add "M-m") ; M-m is common in Spacemacs : ;; (setq fcitx-use-dbus t) ; uncomment if you're using Linux
NOTE: In Linux, using the =dbus= interface has a better performance. But if you also set =echo-keystrokes=, you may experience a lagging issue. See [[https://github.com/cute-jumper/fcitx.el/issues/30][#30]]. If that is something you can't tolerate, don't change the value of =fcitx-use-dbus=.
Features This package comes with a bunch of features to provide better =fcitx= integration for Emacs. For every feature, you can enable or disable it using the corresponding =-turn-on= or =-turn-off= command.
To simplify the configuration, we provide two different setup commands, =fcitx-default-setup= and =fcitx-aggressive-setup=. They will enable different lists of features. You can choose the setup command that fits your need best. For users who want a better control, you can define and use your own setup command by enabling the features you want using the =*-turn-on= commands.
* The Feature List X* indicates that the corresponding feature is enabled.
| Feature | fcitx-default-setup | fcitx-aggressive-setup | |-----------------------------+---------------------+------------------------| | Prefix-key | X | X | | Evil | X | X | | Character & key input | X | X | | M-x,M-!,M-& and M-: | X | | | Disable fcitx in minibuffer | | X | | org-speed-command support | X | X | | Isearch | | |
** Features Enabled in Both Setup Commands The following features are enabled in both =fcitx-default-setup= and =fcitx-aggressive-setup=. You don't have to do anything if you're satisfied with the default settings. *** Disable Fcitx by Prefix Keys
Why this feature
If you've enabled fcitx, then you can't easily change your buffer by =C-x b= because the second key, =b=, will be blocked by fcitx(and you need to press =enter= in order to send =b= to emacs). This feature allows you to temporarily disable fcitx after pressing some prefix keys you've defined.
What do the pre-defined setup comamnds do
Both setup comamnds define =C-x= and =C-c= to be such prefix keys, which means fcitx will be disabled after =C-x= or =C-c= is pressed. This setting should be enough for most users.
For Spacemacs users
If you're a Spacemacs user who uses it in the Emacs way(or hybrid mode), it is possible that you want =M-m= to be the prefix key too. You can use the following command to add =M-m=: : (fcitx-prefix-keys-add "M-m")
For users who want more customizations
You can define the prefix keys as you want: : (fcitx-prefix-keys-add "C-x" "C-c" "C-h" "M-s" "M-o")
After defining prefix keys, you need to call : (fcitx-prefix-keys-turn-on) to enable this feature.
Of course, you can use : (fcitx-prefix-keys-turn-off) to disable this feature. *** Evil Support
Why this feature
This feature allows you to disable fcitx when you exit the "insert mode" and to reenable fcitx after enter "insert mode". Similar to [[https://github.com/vim-scripts/fcitx.vim][fcitx.vim]].
In addition, it will also disable fcitx if you use =switch-to-buffer= or =other-window= to switch to a buffer which is not in "insert mode". For example, if you're currently in "insert mode" in buffer =A= and you've enabled fcitx, then you call =switch-to-buffer= to switch to another buffer =B=, which is currently, say, in normal mode, then fcitx will be disabled in buffer =B=.
What do the pre-defined setup comamnds do
Both setup commands enable this feature. By default, =fcitx.el= consider both =evil-insert-state= and =evil-emacs-state= as "insert mode". Any transition from =evil-insert-state= or =evil-emacs-state= to any other evil state will disable fcitx if necessary.
How to customize it
The evil states in which fcitx should be enabled are defined in the variable =fcitx-active-evil-states=. The default value is =(insert emacs)=, which means fcitx will be enabled if necessary when entering =evil-insert-state= or =evil-emacs-state=. For Spacemacs users who use its hybrid mode, you may also want to add hybrid mode to the list: : (setq fcitx-active-evil-states '(insert emacs hybrid))
Bugs
Note that currently the Evil support is not perfect. If you come across any bugs, consider filing an issue or creating a pull request.
*** Character & Key Input Support
Why this feature
Case 2: You're using =C-h k= to see the binding for a key sequence.
In both cases, fcitx will block your input. This feature can make =fcitx= automatically disabled when you're required to input a key sequence or a character.
What do the pre-defined setup comamnds do
Both commands call =(fcitx-read-funcs-turn-on)= to enable this feature.
What if I don't want it
Use =(fcitx-read-funcs-turn-off)= to disable it.
*** =org-speed-command= Support
Why this feature
This feature allows fcitx to be disabled when the cursor is at the beginning of an org heading so that you can use speed keys such as =n= and =p=.
What do the pre-defined setup comamnds do
Both commands call =(fcitx-org-speed-command-turn-on)= to enable this feature.
What if I don't want it
Use =(fcitx-org-speed-command-turn-off)= to disable it.
* Features Enabled ONLY* in =fcitx-default-setup= Command *** =M-x=, =M-!=, =M-&= and =M-:= Support
Why these features
Usually you don't want to type Chinese when you use =M-x=, =M-!= (=shell-command=), =M-&= (=async-shell-command=) or =M-:= (=eval-expression=). You can automatically disable fcitx when you're using these commands.
What does fcitx-default-setup do
It enables these features by calling the following commands: : (fcitx-M-x-turn-on) : (fcitx-shell-command-turn-on) : (fcitx-eval-expression-turn-on)
Your =M-x= binding should be one of =execute-extended-command= (the default =M-x= command), =smex= , =helm-M-x= and =counsel-M-x=.
WARNING: If you rebind =M-x= to =smex=, =helm-M-x=, or =counsel-M-x=, then you should call =fcitx-default-setup= or =fcitx-M-x-turn-on= after the key rebinding.
How to customize it
You can enable some of the above three features by calling their corresponding =*-turn-on= commands, but remember if you rebind your =M-x=, you should call =(fcitx-M-x-turn-on)= after the key rebinding.
* Features Enabled ONLY* in =fcitx-aggressive-setup= Command *** Disable Fcitx in Minibuffer
Why this features
For me, I personally don't need to type Chinese in minibuffer, so I would like to temporarily disable fcitx in minibuffer, no matter in what kind of command. If you are the same as me, then you could choose this setup.
What does fcitx-aggressive-setup do
Unlike =fcitx-default-setup=, it would not turn on =M-x=, =M-!=, =M-&= and =M-:= support. Instead, it will call =fcitx-aggressive-minibuffer-turn-on= to temporarily disable fcitx in all commands that use minibuffer as a source of input, including, but not limited to, =M-x=, =M-!=, =M-&= and =M-:=. That is why this is called "aggressive-setup". For example, if you press @@html:@@C-x b@@html:@@ to switch buffer, or press @@html:@@C-x C-f@@html:@@ to find file, fcitx will be disabled when you are in the minibuffer so that you can type English letters directly. However, if you choose =fcitx-default-setup=, fcitx will not be disabled after you press @@html:@@C-x b@@html:@@ or @@html:@@C-x C-f@@html:@@. I prefer this more aggressive setup because I don't use Chinese in my filename or buffer name.
** Extra Functions That are not Enabled in Both Commands These functions are not enabled in either =fcitx-default-setup= or =fcitx-aggressive-setup=. You need to enable them manually if you want to use them. *** I-search Support Usually when you use fcitx, you also want to I-search in Chinese, so this feature is not enabled by eith =fcitx-default-setup= or =fcitx-aggressive-setup=. If you do want to disable fcitx when using I-search, enable this feature explicitly by : (fcitx-isearch-turn-on)
Using D-Bus Interface For Linux users, it is recommended that you set =fcitx-use-dbus= to be non-=nil= to speed up a little (but pay attention to the lagging issue mentioned above): : (setq fcitx-use-dbus t) ;; or 'fcitx5 if you use fcitx5
For OSX users who use [[https://github.com/CodeFalling/fcitx-remote-for-osx][fcitx-remote-for-osx]], don't set this variable.
Work with Other Input Methods Although this package is named =fcitx.el=, it is not tightly coupled with =fcitx= itself. =fcitx.el= makes use of the tool =fcitx-remote= (or the dbus interface in Linux) to do the following two things:
If you want to add support for other input methods, as long as it is possible to achieve the above two things from Emacs Lisp, then you get all the functionalities in =fcitx.el= for free. That said, you just need to provide three functions:
So we can see that the functionalities provided in this package is very general, which can be easily adapted to used with other input methods.
TODO TODO
For more features, pull requests are always welcome!