Basic concept/zh-cn

插件

Fcitx 是一个输入法框架，可以通过插件进行高度扩展。Fcitx 5 中有四种不同类型的插件。

前端

前端插件是一种与应用程序通信的插件。它的主要任务是创建输入上下文并向 InputContextManager 注册输入上下文。

输入法引擎

输入法引擎从输入上下文接收用户输入。它将用户输入（通常是按键事件）翻译成文本。每个输入法引擎都可能提供多种不同的输入法。

用户界面

用户界面是一种插件，它显示用户界面和来自其他插件的信息。Fcitx 本身带有两种不同的实现。通常情况下，除非有特殊需要，否则不应实现自己的用户界面插件。另见 自定义主题 了解两个内置的用户界面插件。

模块

这是一种不属于任何其他类别的插件。

• 其中一些提供了子输入模式，例如，用他们的 Unicode 输入字符。
• 其中一些提供与桌面的集成，例如基于状态通知程序的托盘图标的通知项目。
• 其中一些管理与显示服务器的低级连接，例如 xcb/wayland。
• 其中一些甚至可以提供与其他语言的集成，例如luaaddonloader。

输入上下文

输入上下文表示 Fcitx 服务器的客户端。通常，输入上下文可以映射到应用程序、应用程序的窗口或显示服务器的全局上下文。当输入上下文有焦点时，意味着这个特定的客户端被用户主动使用，输入上下文的窗口也应该有焦点。

基于不同的显示服务器，输入上下文可能属于不同的焦点组。每个焦点组都映射到一个显示连接，例如 X11、Wayland。每个焦点小组都包含一组输入上下文，并且最多其中一个将在小组中获得焦点。输入上下文也可能没有焦点小组。

Event handling

There are 5 stage of event handling for one event, only 3 of the stages are exposed to user, which are Default, PreInputMethod, and PostInputMethod. There are also ReservedFirst and ReservedLast used by Fcitx internally. The order of different stages is ReservedFirst, PreInputMethod, Default, PostInputMethod, ReservedLast. The Default stage just after the active input method engine receives event. PreInputMethod is one of the most commonly used one to implement sub input method. For example, an addon may define a trigger key. When the trigger key is pressed by user, it sets a flag and handle all the future key event in the PreInputMethod stage until it ends its input mode.

As for the event type, there are input context specific events and global events. The input context specific events always associate with an input context.

Life of a Key Event

From an actual physical keyboard press to the key event that receives by Fcitx may go through following steps.

Reaching Fcitx Frontend

Depending on the protocol between Fcitx and application, there are several different path that might be exercised.

Fcitx frontend is where Fcitx receives the key event from application and display server.

XIM

Upon application receives a KeyEvent from X Server, it need to use XIM protocol to forward it to the XIM server. The key event contains only modifier state and key code. The actual key sym is derived from the X Server key map.

DBusFrontend/IBusFrontend/Fcitx4Frontend

These frontends are similar, but just using different dbus interfaces. When application receives a key event from toolkit (e.g. Gtk/Qt/SDL), it forward the key event to Fcitx via some dbus interfaces. The key sym comes from the translation inside the application, but key code and modifier state are also available.

Wayland IM

There's zwp_input_method_v1 and zwp_input_method_v2. In V1, the key event is from application and goes through a similar code path like DBus. In V2, Input method will need to create a keyboard grab and Compositor will forward all the key to input methods. The key code to key sym translation is done on the Fcitx side, with the keymap from compositor.

From Frontend to Fcitx event pipe line and Input Method Engine

Inside Fcitx, The Key event will be wrapped as a KeyEvent object, and be processed by the Fcitx event pipeline. Before sending to the pipeline, if the current layout to be used is not same as the system layout, Fcitx will apply its own XKB translation and store the translated key object in the field rawKey. The field key() will be updated accordingly as a normalized rawKey form.

Then it goes through multiple stages and it might be filtered in the middle of the pipeline to prevent any future process.