Addon Type

<translate1>

Intro to Fcitx addon system

Nearly everything in fcitx is an addon, which is basically a shared library with necessary configuration files.

File Structure

In order to register an addon with Fcitx, you first need a configuration file like this:

[Addon]
Name=fcitx-pinyin
GeneralName=Pinyin
GeneralName[zh_CN]=拼音
Comment=Simple Pinyin support for Fcitx
Comment[zh_CN]=Fcitx 简单的拼音支持
Category=InputMethod
Enabled=True
Library=fcitx-pinyin.so
Type=SharedLibrary
SubConfig=Shuang Pin Schema:native:pinyin/sp.dat,Symbol:native:pinyin/pySym.mb,fcitx:domain

As you can see, this file is stored in Ini format, and use similar strategy as desktop file to do the i18n work (But please remember, Fcitx doesn't really use desktop like KDE, Fcitx just uses the similar idea.).

Name entry is the name entry for Fcitx.

Info: Why not using UUID here? Because every part of Fcitx is highly integrated, it doesn't make much sense to use UUID, since it's not generated at runtime, but it's defined as configuration. Other addon maybe need to use the Inter module function call.

GeneralName and Comment entries are designed to be displayed in configuration tool, which is basically a piece of short description text and a piece of long description text.

Category describe the type of this Addon, different Addon uses different interface, which need to be identified here.

Type and Library defines the name of library and the type of addon. Currently Fcitx only supports Shared Library, and Library will be the library name.

Info: There was once a DBus type for Fcitx, but since there is no urgency need for such addon, so this idea was postponed.

SubConfig is a complext string, separated by comma, each entry inside it will be <Description Text>:<type>[:<additional value>], in above example, it introduce two simple text file to be opened, and there always need to be a <domain name>:domain entry to describe "which domain are these SubConfig strings in".

Currently, type can be "configfile", "native", or "domain". "native" defines a simple text filename in description, which cannot have wildcard in filename. Description of "configfile" contains filename with wildcard and configuration description file name. "domain" defines gettext domain of this module. Names of "configfile" and "native" are translatable, translation should live in the "domain" defined by subconfig.

Shared Library Addon

Each addon need to expose a symbol to be picked up by fcitx, as it's function interface.

FcitxFrontend frontend; /* for frontend */
FcitxIMClass ime; /* for input method */
FcitxModule module; /* for module */
FcitxUI ui; /* for user interface */

And all Shared Library Addon need not to link with Fcitx library, which means there is no license limit for addon of Fcitx.

Since 4.1.2, there is a ABI check provided by Fcitx, for addon, there is some additonal lines need to be added to the source code.

FCITX_EXPORT_API
int ABI_VERSION = FCITX_ABI_VERSION;

FCITX_ABI_VERSION is a macro defined in fcitx/fcitx.h, which is a simple number which defines the internal ABI version. The version must be exactly matched, otherwise Fcitx will refuse to load this addon. For Fcitx version x.y.z, if x.y keep the same, Fcitx will not change the ABI version, but possibly to add some new API.

Make addon configurable

There is no necessary code needed for if you only need a simple key value configuration. All the thing you need is a <addon name>.desc placed in configdesc/. The user interface is automatically generated by configuration tool at runtime, make Fcitx can be easily ported to all platform and keep itself behaviour native.

</translate>