docs/en/Community-Developer-Guides/System_Input_Method_Adaptat...

562 lines
19 KiB
Markdown

__openKylin OS Input Method Adaptation Guide__
# 1\. __Background__.
This document provides the introduction of fcitx5 input method framework built in openKyLin OS and the details of the work needed to adapt the input method engine to fcitx5.
# 2\. __fcitx5 input method framework__
## 2\.1 __Introduction__
### 2\.1\.1 __Overall design architecture
fcitx5 input method framework adopts plug-in design. In this design, it contains one fcitx5 input method framework service and several plug-in dynamic libraries. The main modules are introduced below.
#### 2\.1\.1\.1\.1 __ fcitx5 input method framework service__
fcitx5 input method framework service is a service provided by fcitx5 executable program. This service is responsible for loading each plugin dynamic library and communicating with other modules.
#### 2\.1\.1\.1\.2 __front-end plug-in module__
fcitx5 input method framework has several front-end plug-in modules, namely dbusfrontend, fcitx4frontend, ibusfrontend, waylandim, xim. used to be compatible with different system environments and applications.
#### 2\.1\.1\.1\.2\.1 __dbusfrontend__
dbus frontend plugin is implemented by fcitx5's own protocol, Qt/GTK input method module use this frontend plugin to communicate with fcitx5.
#### 2\.1\.1\.2\.2 __fcitx4frontend__
#### fcitx4 frontend plug-in provides support for applications of input method module that use fcitx4 dbus protocol.
#### 2\.1\.1\.2\.3 __ibusfrontend__
ibus frontend plugin implements ibus protocol.
#### 2\.1\.1\.2\.4 __waylandim__
waylandim implements Wayland's server-side protocol for providing input method protocols.
#### 2\.1\.1\.1\.2\.5 __xim__
xim implements the server-side protocol for X11's input method protocol.
#### 2\.1\.1\.1\.3 __UI plugin module__
fcitx5 input method framework provides three UI plug-ins, which are classic UI plug-in, kimpanel UI plug-in, and virtualkeyboard UI plug-in.
#### 2\.1\.1\.1\.3\.1 __classic UI__
UI plugins used by default by fcitx5 and already integrated in the input method framework.
#### 2\.1\.1\.1\.3\.2 __kimpanel UI__
UI proxy plugin for the physical keyboard input window used by fcitx5. The adaptation requires the implementation of the kimpanel server. The plugin uses the DBus interface to communicate with the server.
#### 2\.1\.1\.1\.3\.3 __virtualkeyboard UI__
Virtual keyboard UI proxy plugin used by fcitx5. The adaptation requires the implementation of a virtual keyboard server. The plugin uses the DBus interface to communicate with the server.
#### 2\.1\.1\.1\.4 __Input Method Engine Plugin Module__
The fcitx5 input method framework defines the interface used by the input method engine plug-in. If any input method engine implements this interface and export the input method engine object in certain format, then fcitx5 input method framework can load and use this input method engine correctly.
### 2\.1\.2 __basic working principle__
Multiple front-end plug-in modules of fcitx5 input method framework are implemented to support multiple input method protocols and GUI frameworks, including XIM, Wayland, ibus and other input method protocols and Qt, GTK and other GUI frameworks.
Among them, the dbus frontend module is responsible for dbus communication with the input method plugins of Qt and GTK GUI frameworks.
Take Qt5 application as an example, here is a brief introduction of Qt5 application's interaction with input method engine through fcitx5 input method framework. The basic principle schematic is shown as follows.
![inputmethod.png](./assets/system_input_method_adaptation_guide/inputmethod.png)
#### 2\.1\.2\.1 __Qt5 input method module__
fcitx5\-qt project implements Qt5 defined input method interface and interface to communicate with dbus front-end plug-in of fcitx5 input method framework, so that events in Qt5 program can be sent to fcitx5 input method framework.
#### 2\.1\.2\.2 __dbus front-end plugin__
Receive dbus signals sent from Qt or GTK program through dbus or call
#### 2\.1\.2\.3 __fcitx5 input method framework__
dbus front-end plug-in will do some processing of event or function call and then call the function in fcitx5 input method framework, usually call the method of InputContext object to send an event to fcitx5 input method framework
#### 2\.1\.2\.4 __UI proxy plugin__
fcitx5 input method framework supports multiple UI display methods, including classic UI plugin using X11 API and kimpanel plugin using remote display service. The UI proxy plugin in the schematic says kimpanel plugin, while impanel is the corresponding remote display service. This service can display the input window of the physical keyboard input method.
#### 2\.1\.2\.5 __Input Method UI Service__
If the input method framework uses a UI proxy plugin, the UI proxy plugin communicates with the corresponding input method UI service.
#### 2\.1\.2\.6 __Input Method Engine Plugin__
After fcitx5 input method framework receives keystroke event, after some processing, it will call the function of input method engine plug-in which implemented InputMethodEngine API defined by fcitx5. Communication with input method engine service is realized through functions in plug-in
#### 2\.1\.2\.7 __InputMethodEngine__
The input method engine implements the real logic of the input method. The input method engine can either be wrapped directly in the input method engine plug-in, or the communication between the input method engine and the input method engine plug-in can be implemented by means of IPC communication.
## 2\.2 __ Support for physical keyboard input method engine
### 2\.2\.1 __UI support__
fcitx5 provides physical keyboard input method UI proxy plugin based on DBus protocol: kimpanel. the module is located in fcitx5/src/ui/kimpanel directory.
#### 2\.2\.1\.1 __DBus service__
#### 2\.2\.1\.1\.1 __DBus service name__
org\.kde\.kimpanel\.inputmethod
##### 2\.2\.1\.1\.2 __DBus object path__
/kimpanel
##### 2\.2\.1\.1\.1\.3 __DBus interface name__
org\.kde\.kimpanel\.inputmethod
#### 2\.2\.1\.2 __DBus signal__
The dbus signals provided by kimpanel can be called by kimpanel to enable communication from kimpanel to impanel. The impanel UI service is responsible for responding to these signals.
#### 2\.2\.1\.2\.1 __ExecDialog__
Show dialog box
#### 2\.2\.1\.2\.2\.2 __ExecMenu__
Show menu
#### 2\.2\.1\.2\.3 __RegisterProperties__
Register menu items
#### 2\.2\.1\.2\.4 __UpdateProperty__
Update a menu item
#### 2\.2\.1\.2\.5 __RemoveProperty__
Remove a menu item
#### 2\.2\.1\.2\.6 __ShowAux__
Whether to show Aux prompt text
#### 2\.2\.1\.2\.7 __ShowPreedit__
Whether to show the pre-edit string
#### 2\.2\.1\.2\.8 __ShowLookupTable__
Whether to show candidate results
#### 2\.2\.1\.2\.9 __UpdateLookupTableCursor__
Update the input position cursor
#### 2\.2\.1\.2\.10 __updatePreeditCaret__
Update the pre-edit string cursor
#### 2\.2\.1\.2\.11 __UpdatePreeditText__
Update the pre-edit text
#### 2\.2\.1\.2\.2\.12 __UpdateAux__
Update the aut auxiliary text
#### 2\.2\.1\.2\.2\.13 __UpdateSpotLocation__
#### 2\.2\.1\.2\.14 __UpdateScreen__
#### 2\.2\.1\.2\.15 __Enable__
Enables or disables the input window
#### 2\.2\.1\.3 __DBus method__
The dbus method provided by kimpanel can be called by the impanel UI service to enable communication from impanel to kimpanel
#### 2\.2\.1\.3\.1 __Exit__
Exit fcitx5 input method framework service
#### 2\.2\.1\.3\.2 __ReloadConfig__
Restart input method framework service on fcitx5
#### 2\.2\.1\.3\.3 __Configure__
Start fcitx5 configuration tool
#### 2\.2\.1\.3\.4 __LookupTablePageUp__
Candidate result page up
#### 2\.2\.1\.3\.5 __LookupTablePageDown__
LookupTablePageDown
#### 2\.2\.1\.3\.6 __SelectCandidate__
Selects the specified candidate result
#### 2\.2\.1\.3\.7 __PanelCreated__
Physical keyboard input method input window created successfully
#### 2\.2\.1\.3\.8 __PanelCreated2__
The physical keyboard input window was created successfully.
#### 2\.2\.2 __Input Method Engine Support__
fcitx5 provides input method engine APIs: InputMethodEngine, InputMethodEngineV2, InputMethodEngineV3 and InputMethodEngineV4. Among them, InputMethodEngineV4 adds support for virtual keyboard input method keypress events.
#### 2\.2\.2\.2\.1 __input_engine_API__
#### 2\.2\.2\.1\.1 __keyEvent__
Function: The main function of the input method to handle key events.
Parameters: const InputMethodEntry &entry,KeyEvent &keyEvent
Return value type: void
#### 2\.2\.2\.2\.1\.2 __activate__
Function: Activate the engine
Parameters
Return value type
#### 2\.2\.2\.2\.1\.3 __deactivate__
Function: Deactivate the engine
Parameter
Return value type
#### 2\.2\.2\.2\.1\.4 __reset__
Function: Reset
Parameter
Return value type
#### 2\.2\.2\.1\.5 __filterKey__
Function: Process key events \ (key events not processed elsewhere \)
Parameters: input method entry, key event
Return value type: void
Implementing the simplest physical input method only requires overriding the keyEvent function.
## 2\\.3 __ Support for virtual keyboard input method engine
### 2\.3\.1 __UI support__
fcitx5 provides virtual keyboard UI plugin based on DBus protocol: virtualkeyboard UI in fcitx5/src/ui/virtualkeyboard. The information and interface of this plugin are shown below.
#### 2\.3\.1\.1 __DBus service__
#### 2\.3\.1\.1\.1 __DBus service name__
org\.fcitx\.Fcitx5\.VirtualKeyboardBackend
#### 2\.3\.1\.1\.2 __DBus object path__
/virtualkeyboard
#### 2\.3\.1\.1\.3 __DBus interface name__
org\.fcitx\.Fcitx5\.VirtualKeyboardBackend1
#### 2\.3\.1\.2 __DBus signal__
#### 2\.3\.1\.2\.1 __ShowVirtualKeyboard__
Function: The display signal sent to the virtual keyboard.
Parameters: None.
#### 2\.3\.1\.2\.2 __HideVirtualKeyboard__
Function: The hidden signal sent to the virtual keyboard.
Parameters: None.
#### 2\.3\.1\.2\.3 __UpdatePreeditCaret__
Function: Signal sent to the virtual keyboard to set the pre-edit text cursor position.
Parameters.
int preeditCursor, the number of the cursor location.
#### 2\.3\.1\.2\.4 __UpdatePreeditArea__
Function: Signal sent to the virtual keyboard to set the pre-edit text.
Parameters.
string preeditText, the pre-edit text.
#### 2\.3\.1\.2\.5 __UpdateCandidateArea__
Function: Signal sent to the virtual keyboard to set the candidate words
Parameters.
vector<std::string> &candidateTextList, the set of candidate words for the current page, each element is a candidate word.
bool hasPrev, if or not the previous page candidate exists.
bool hasNext, if or not the next page candidate exists.
int pageIndex, the page number of the current candidate page.
#### 2\.3\.1\.2\.6 __NotifyIMActivated__
Function: Send the current input method activation signal to the virtual keyboard.
Parameters.
string uniqueName, the name of the current input method.
#### 2\.3\.1\.2\.7 __NotifyIMDeactivated__
Function: Send the current input method deactivated signal to the virtual keyboard.
Parameters
string uniqueName, the name of the current input method.
#### 2\.3\.1\.2\.8 __NotifyIMListChanged__
Function: Send a notification signal to the virtual keyboard that the current input method list has changed.
Parameters: None.
#### 2\.3\.1\.1\.3 __DBus method__
#### 2\.3\.1\.3\.1 __ProcessKeyEvent__
Function: Receives key events sent by the virtual keyboard and forwards them to the input method framework.
Parameters.
uint32\_t keyval, the value represented by the current key under the current keyboard layout, in English it is the ASCII code corresponding to the key.
uint32\_t keycode, the unique tag value of the current key in all keyboard layouts, defined in Linux.
uint32\_t state, modifier state of key, such as Shift, Caps Lock, etc. Details can be found in fcitx5/src/lib/fcitx\-utils/keysym\.h.
bool isRelease, if or not the key is pressed, true is lift, false is pressed.
uint32\_t time, timestamp when key is pressed, default is 0.
#### 2\.3\.1\.3\.2 __ProcessVisibilityEvent__
Function: Receive the virtual keyboard visibility event sent by the virtual keyboard and update the visibility information in the backend module.
Parameters
bool visible, the visibility of the virtual keyboard, true is showing, false is hidden
#### 2\.3\.1\.3\.3 __SelectCandidate__
Function: Receive the serial number of the candidate word selected by the virtual keyboard, and up-screen the candidate word.
Parameters
int index, the serial number of the candidate word selected by user.
#### 2\.3\.1\.3\.4 __PrevPage__
Function: Receive the candidate word page request sent by virtual keyboard, switch to the previous page of the candidate word.
Parameters: None.
#### 2\.3\.1\.3\.5 __NextPage__
Function: Receive the page flip request from the virtual keyboard, and switch to the next page of candidates.
Parameters: None.
### 2\.3\.2 __Input method engine support__
InputMethodEngineV4 of fcitx5 input method engine adds virtualKeyboardEventImpl function to provide support for virtual keyboard input method key event, the related code is in fcitx5/src/lib/fcitx/inputmethodengine.
If input method engine wants to provide support for virtual keyboard keystroke events, it needs to implement InputMethodEngineV4 interface. Otherwise, just consider to implement other three interfaces for physical keyboard input method engine.
# 3\. __Adapt fcitx5 input method framework__
## 3\.1 __Physical keyboard input method engine adaptation__
### 3\.1\.1 __UI adaptation
fcitx5 provides default physical keyboard input method input window UI, which can be simply divided into two kinds without considering special client side input method UI: classic UI and kimpanel UI.
#### 3\.1\.1\.1\.1 __classic UI__
This UI is the input window UI provided by fcitx5 using underlying API\(X11, wayland\).
#### 3\.1\.1\.1\.2 __kimpanel UI__
This UI is an input window UI proxy provided by fcitx5, which defines several dbus APIs to communicate with remote physical keyboard input UI service. This module is originally provided to solve the problem that input window is not visible due to global search interface overlay on Ubuntu.
To simplify the adaptation, third-party input methods can consider directly adapting the dbus interface defined by this UI proxy module.
If you want to provide a more comprehensive customization, you should also consider providing a UI proxy module similar to kimpanel.
### 3\.1\.2 __Input Method Engine Adaptation__
#### 3\.1\.2\.1 __Input method configuration file writing__
The configuration files are divided into plugin configuration files and input method configuration files, and the fields in each configuration file have different meanings.
Addon configuration file: addon configuration file is installed in addon directory /share/fcitx5/addon/.
Example of Pinyin input method addon configuration file.
```c++
[Addon]
Name[ca]=Pinyin
Name[da]=Pinyin
Name[de]=Pinyin
Name[he]=פיניין:
Name[ko]=병음
Name[ru]=Пиньинь
Name[zh_CN]=Pinyin
Name=Pinyin
Category=InputMethod
Version=5.0.11
//The corresponding pinyin input method so is libpinyin.so
Library=libpinyin
Type=SharedLibrary
OnDemand=True
Configurable=True
//Addon dependencies
[Addon/Dependencies]
0=punctuation
```
Input method configuration file: input method configuration file is saved in input method directory /share/fcitx5/inputmethod/.
For example, Pinyin input method engine configuration file.
```c++
[InputMethod]
Name[ca]=Pinyin
Name[da]=Pinyin
Name[de]=Pinyin
Name[he]=פיניין:
Name[ko]=병음
Name[ru]=Пиньинь
Name[zh_CN]=Pinyin
Name=Pinyin
//Icon name for Pinyin input method
Icon=fcitx-pinyin
Label=Pinyin
LangCode=zh_CN
//Input method corresponding to the plug-in
Addon=pinyin
//Whether to support customization
Configurable=True
ðŸ™' ðŸ™'
#### 3\.1\.2\.2 __Project CMakeLists file compilation__
The project file CMakeLists file defines the compilation behavior of the input method source code file. It includes the libraries to be linked during compilation and the configuration file installation path, etc. Take the pinyin input method as an example.
```sh
#pinyin
add_library(pinyin SHARED pinyin.cpp)
target_link_libraries(pinyin PRIVATE Fcitx5::Core)
set_target_properties(pinyin PROPERTIES PREFIX "")
install(TARGETS pinyin DESTINATION "${FCITX_INSTALL_LIBDIR}/fcitx5")
#pinyin-addon configuration file conversion and installation
#export pinyin-addon.conf.in to pinyin-addon.conf
configure_file(pinyin-addon.conf.in pinyin-addon.conf)
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/pinyin-addon.conf" RENAME quwei.conf DESTINATION "${FCITX_INSTALL_PKGDATADIR}/addon")
# Defines the installation path of the pinyin engine configuration file
# Input Method registration file
install(FILES "pinyin.conf" DESTINATION "${FCITX_INSTALL_PKGDATADIR}/inputmethod")
```
#### 3\.1\.2\.3 __Implementation of physical input method engine interface__
The input method engine part of the adaptation that is to rewrite the defined engine related interfaces, the main one is InputMethodEngine::keyEvent\(\). Take the tinyin input method as an example.
Inherit the AddonFactory plugin factory class and create a pinyin input method engine plugin class
```c++
class PinyinEngineFactory : public AddonFactory {
public:
AddonInstance *create(AddonManager *manager) override {
registerDomain("fcitx5-chinese-addons", FCITX_INSTALL_LOCALEDIR);
return new PinyinEngine(manager->instance());
}
};
```
Pinyin Engine plugin class inherits InputMethodEngineV3 and implements the relevant interface functions. Such as activate\(\), deactive\(\), keyEvent\(\) and reset\(\) interfaces
```c++
class PinyinEngine final : public InputMethodEngineV3 {
public :
PinyinEngine(Instance *instance);
~PinyinEngine();
Instance *instance() { return instance_; }
void activate(const InputMethodEntry &entry,
InputContextEvent &event) override;
void deactivate(const InputMethodEntry &entry,
InputContextEvent &event) override;
void keyEvent(const InputMethodEntry &entry, KeyEvent &keyEvent) override;
void reset(const InputMethodEntry &entry,
InputContextEvent &event) override;
...
};
```
## 3\.2 __Virtual keyboard input method engine adaptation__
### 3\.2\.1 __UI adaptation
fcitx5 provides a default UI proxy module for virtual keyboard input method input window: virtualkeyboard UI.
To simplify the adaptation, third-party input methods can consider directly adapting the dbus interface defined by this UI proxy module.
If you want to provide more comprehensive customization, you should also consider providing a UI proxy module similar to virtualkeyboard.
### 3\.2\.2 __Input Method Engine Adaptation__
The virtual keyboard engine adaptation is basically similar to the physical keyboard keyboard engine adaptation, the only difference is that the virtual keyboard engine needs to implement the virtualKeyboardEventImpl virtual function in the InputMethodEngineV4 class.
# __Reference Documentation__
Input method engine related code documentation: https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputMethodEngine.html
Implementing a simplest input method: https://fcitx-im.org/wiki/Develop_an_simple_input_method