19 KiB
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.
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.
vectorstd::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.
[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.
[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
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
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