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 阶段中的所有未来键事件，直到它结束其输入模式。

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

关键事件的生命周期

从实际的物理键盘按下到 Fcitx 接收到按键事件可能会经过以下步骤。

到达 Fcitx 前端

根据 Fcitx 和应用程序之间的协议，可以使用几种不同的路径。

Fcitx 前端是 Fcitx 从应用程序和显示服务器接收按键事件的地方。

XIM

应用程序从 X Server 收到 KeyEvent 后，需要使用 XIM 协议将其转发到 XIM 服务器。按键事件仅包含修饰符状态和按键代码。实际的密钥符号来自 X 服务器密钥映射。

DBus前端/IBus前端/Fcitx4前端

这些前端很相似，只是使用了不同的 dbus 接口。当应用程序从工具包（例如Gtk/Qt/SDL）接收到按键事件时，它通过一些dbus接口将按键事件转发给Fcitx。密钥符号来自应用程序内部的翻译，但密钥代码和修饰符状态也是可用的。

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.