Q&A for developer
This is a page to answer some questions. Some of the questions are asked frequently, others are the common pitfalls that I think it is worth to answer/mention.
I do not like Fcitx's default UI and want to have my own one for my own engine.
This is a question that is frequently asked by third party proprietary input method engine developer. From Fcitx developer point of view, the answer would be NO, don't do this. The rational behind this answer is due to the complex situation of Linux display server.
- X11, where you can move the window freely.
- Wayland + Fcitx IM Module, the window might be rendered by client, where you have basically no control. We can not allow Fcitx IM Module to have another plugin system which would introduce too much complexity and possibly too much memory foot print for application.
- Wayland + text-input + zwp-input-method, the popup surface need to use special wayland protocol, which may not be accessible from random process. Only input method server may have permission to display such input window.
In summary, due to the restriction on wayland, it may be impossible to display input window properly if you choose to implement your own version.
If you want to do that anyway, what you should be aware of is that, you likely do not want to implement a new Kimpanel or a new User Interface addon. For Kimpanel, it is designed to be integrate with desktop and there can be only one kimpanel service. If you want to implement Kimpanel, it is possible that the desktop itself already have a Kimpanel service running. There is no such a mechanism to replace another kimpanel and return the kimpanel dbus name back to the original one. Implement either Kimpanel, or User Interface, it have to be generic and support other existing input method. If you think that this is not you want to do, you'd better only implement the UI for yourself. Which means you should avoid all the built-in UI mechanism with in Fcitx except the client side preedit. Just simply do not set any value to the InputContext::inputPanel() in Fcitx and keep it empty. And for your proprietary user interface process, you may want to use a inter process mechanism such as DBus to send the information over. You may reuse the dbus interface like Kimpanel, just be sure to only use your own DBus name and do not try to become Kimpanel.
There are some option looks like can be reused from global config, should I use it?
For input method engine, some global config option such as previous page key, next page key, it may be used, but you may also want to use the one in your own config. There is not such a default value good for every input method engine. This default option is intended to be used by addons that don't want to provide there own previous page key and next page key.
For example, lots of Pinyin user are commonly using minus and equal key as paging, but such key may not even be a good option if you're not using US keyboard layout. In the global config, we only assign very generic keys that is likely to work for every keyboard layout, such as arrow key.
How do I test the input method?
Fcitx provides a small testing framework, that allows you to simulate key event. Please refer to
fcitx-utils/testing.h for more details. See also testquickphrase.cpp as an good example about how to simulate key events and sending it to fake input context.
Should I use surrounding text feature?
There are a good amount of applications that would never work with it. For example, xim based client doesn't work (xterm, wine, etc), SDL application. Terminals are also a good case if you just think about it.
It can also be buggy in certain applications if they are not using system built-in widget, especially for browser. Also, if webages is messing around with how text is displayed (google docs), it may not work there too. And that is pretty bad because we can not check against application's version even if we managed to fix them in some cases. Certain hack can be done by checking application name, but the name of application may not be available under certain cases depending on what protocol is used. Also, embedded terminal window (e.g. konsolepart) is a case where the application name detection workaround fails.
It can be a nice source of supplement of information, but I'd rather not rely on it for everything. For example,
- Japanese usually only use it for "reconvert" (selecting a range of hiragana character and re-initiate the composing with selected text)
- Hangul also only use it for temporary Hanja mode, but it also provides an always-on Hanja mode which won't use surrounding at all (Somewhat similar to macro mode in unikey).
- In Chinese, Fcitx uses it in certain cases just to detect the context and not to modify the surrounding text.
In a word, using the information from surrounding is more reliable than modifying the surrounding text, and it would be better to have an easy way (in the sense of user may figure out an alternative way of typing text really easily) to workaround it when it's not working properly.
Should I use client side preedit text? Can I use all the supported text format?
Can I use multi-line text in user interface?
Yes and No. You can use multi line text in candidate word, but do not use them in preedit and aux string.