Basic concept/zh-cn

插件

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

前端

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

输入法引擎

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

用户界面

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

模块

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

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

输入上下文

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

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

事件处理

一个事件有5个事件处理阶段，只有3个阶段暴露给用户，分别是Default、PreInputMethod和PostInputMethod。还有 Fcitx 内部使用的 ReservedFirst 和 ReservedLast。这些阶段的顺序是 ReservedFirst、PreInputMethod、Default、PostInputMethod、ReservedLast。活动输入法引擎收到事件后的默认阶段。PreInputMethod 是实现子输入法最常用的方法之一。例如，插件可以定义触发键。当用户按下触发键时，它会设置一个标志并处理 PreInputMethod 阶段中的所有未来键事件，直到它结束其输入模式。

至于事件类型，有输入上下文特定事件和全局事件。输入上下文特定事件总是与输入上下文相关联。

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.