Difference between revisions of "Addon Type"
Weng Xuetian (talk | contribs) m (Text replacement - "<translate>" to "<translate1>") |
Weng Xuetian (talk | contribs) (Marked this version for translation) |
||
| (One intermediate revision by the same user not shown) | |||
| Line 1: | Line 1: | ||
<languages/> | <languages/> | ||
| − | < | + | <translate> |
| − | == Intro to Fcitx addon system == | + | == Intro to Fcitx addon system == <!--T:1--> |
Nearly everything in fcitx is an addon, which is basically a shared library with necessary configuration files. | Nearly everything in fcitx is an addon, which is basically a shared library with necessary configuration files. | ||
| − | === File Structure === | + | === File Structure === <!--T:2--> |
In order to register an addon with Fcitx, you first need a configuration file like this: | In order to register an addon with Fcitx, you first need a configuration file like this: | ||
| − | [Addon] | + | <!--T:3--> |
| + | [Addon] | ||
Name=fcitx-pinyin | Name=fcitx-pinyin | ||
GeneralName=Pinyin | GeneralName=Pinyin | ||
| Line 21: | Line 22: | ||
SubConfig=Shuang Pin Schema:native:pinyin/sp.dat,Symbol:native:pinyin/pySym.mb,fcitx:domain | SubConfig=Shuang Pin Schema:native:pinyin/sp.dat,Symbol:native:pinyin/pySym.mb,fcitx:domain | ||
| + | <!--T:4--> | ||
As you can see, this file is stored in [[wikipedia:INI file|Ini format]], and use similar strategy as [http://standards.freedesktop.org/desktop-entry-spec/latest/ desktop file] to do the i18n work (But please remember, Fcitx doesn't really use desktop like KDE, Fcitx just uses the similar idea.). | As you can see, this file is stored in [[wikipedia:INI file|Ini format]], and use similar strategy as [http://standards.freedesktop.org/desktop-entry-spec/latest/ desktop file] to do the i18n work (But please remember, Fcitx doesn't really use desktop like KDE, Fcitx just uses the similar idea.). | ||
| + | <!--T:5--> | ||
Name entry is the name entry for Fcitx. | Name entry is the name entry for Fcitx. | ||
| + | <!--T:6--> | ||
{{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 [[Special:myLanguage/Inter module function call|Inter module function call]]. }} | {{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 [[Special:myLanguage/Inter module function call|Inter module function call]]. }} | ||
| + | <!--T:7--> | ||
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. | 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. | ||
| + | <!--T:8--> | ||
Category describe the type of this Addon, different Addon uses different interface, which need to be identified here. | Category describe the type of this Addon, different Addon uses different interface, which need to be identified here. | ||
| + | <!--T:9--> | ||
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. | 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. | ||
| + | <!--T:10--> | ||
{{Info|There was once a DBus type for Fcitx, but since there is no urgency need for such addon, so this idea was postponed.}} | {{Info|There was once a DBus type for Fcitx, but since there is no urgency need for such addon, so this idea was postponed.}} | ||
| + | <!--T:11--> | ||
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". | 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". | ||
| + | <!--T:12--> | ||
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. | 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 == | + | == Shared Library Addon == <!--T:13--> |
| + | <!--T:14--> | ||
Each addon need to expose a symbol to be picked up by fcitx, as it's function interface. | Each addon need to expose a symbol to be picked up by fcitx, as it's function interface. | ||
| − | FcitxFrontend frontend; /* for frontend */ | + | <!--T:15--> |
| + | FcitxFrontend frontend; /* for frontend */ | ||
FcitxIMClass ime; /* for input method */ | FcitxIMClass ime; /* for input method */ | ||
FcitxModule module; /* for module */ | FcitxModule module; /* for module */ | ||
FcitxUI ui; /* for user interface */ | FcitxUI ui; /* for user interface */ | ||
| + | <!--T:16--> | ||
And all Shared Library Addon need not to link with Fcitx library, which means there is no license limit for addon of Fcitx. | And all Shared Library Addon need not to link with Fcitx library, which means there is no license limit for addon of Fcitx. | ||
| + | <!--T:17--> | ||
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. | 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 | + | <!--T:18--> |
| + | FCITX_EXPORT_API | ||
int ABI_VERSION = FCITX_ABI_VERSION; | int ABI_VERSION = FCITX_ABI_VERSION; | ||
| + | <!--T:19--> | ||
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. | 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 == | + | == Make addon configurable == <!--T:20--> |
| + | <!--T:21--> | ||
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. | 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. | ||
| + | <!--T:22--> | ||
[[Category:Develop]] | [[Category:Develop]] | ||
</translate> | </translate> | ||
Latest revision as of 22:54, 2 February 2016
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.
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.
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.
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.