Develop an simple input method - Revision history

Weng Xuetian at 23:45, 11 January 2025

2025-01-11T23:45:57Z

← Older revision		Revision as of 23:45, 11 January 2025
Line 2:		Line 2:
	<translate>		<translate>
	<!--T:1-->		<!--T:1-->
	This is a step-by-step ~~instruction~~ for writing a Fcitx 5 input method. The same instruction can be used for developing other types of addons, ~~just input method engine is the most complex ones~~.		This is a step-by-step tutorial for writing a Fcitx 5 input method. The same instruction can be used for developing other types of addons. While Fcitx 5 now supports many non traditional Linux/Unix (Mac, iOS, Android) platforms, this tutorial assumes you are using Linux or FreeBSD for development and have basic knowledge about Command-line, C++ and CMake.

	= ~~Understand~~ the ~~file~~ structure ~~for~~ a Fcitx shared library addon = <!--T:2-->		= Understanding the structure of a Fcitx shared library addon = <!--T:2-->
	Fcitx 5 provides a extensible framework for adding new addon types, but ~~shared~~ library ~~support is built in and is the base of~~ all ~~other addon~~ types. ~~So we~~ will ~~only cover shared library~~ addon ~~in this document~~.		Fcitx 5 provides a extensible framework for adding new addon types (Right now Lua is also supported, but only a small set of API is supported). Shared library can access all types of Fcitx API. Static library addon has not difference from API point of view, but you will need to put some more effort to link all addon into server properly.

	<!--T:3-->		<!--T:3-->
Line 24:		Line 24:

	<!--T:4-->		<!--T:4-->
	Above is the file structure for an input method addon. For other types of addons, files under <code>inputmethod/</code> is not needed. The file name of <code>[addon name].conf</code> matters and will be used to uniquely reference this specific addon. Fcitx also follows XDG directory standard, so the files under XDG_DATA_DIR/fcitx5 will also be checked. Similarly, file name of configuration file under <code>inputmethod/</code> also matters and will be the unique name of a certain input method.		Above is the file structure for an input method addon. For other types of addons, files under <code>inputmethod/</code> is not needed. The file name of <code>[addon name].conf</code> matters and will be used to uniquely reference this specific addon. Fcitx also follows [https://specifications.freedesktop.org/basedir-spec/latest/ XDG directory standard], so the files under XDG_DATA_DIR/fcitx5 will also be checked. Similarly, file name of configuration file under <code>inputmethod/</code> also matters and will be the unique name of a certain input method.

	<!--T:5-->		<!--T:5-->
Line 83:		Line 83:

	<!--T:11-->		<!--T:11-->
	The file is in a ini-like format, with certain fcitx specific extensions and rules. It also supports XDG Desktop file style I18N for translation.		The file is in a [[wikipedia:INI_file\|ini-like]] format, with certain fcitx specific extensions and rules. It also supports XDG Desktop file style I18N for translation.

	= Use CMake build system = <!--T:12-->		= Use CMake build system = <!--T:12-->
Line 112:		Line 112:

	<!--T:16-->		<!--T:16-->
	~~You may want to check some CMake~~ tutorial ~~to understand some basic CMake usage.~~		This tutorial ass

	<!--T:17-->		<!--T:17-->

Weng Xuetian at 00:16, 21 March 2024

2024-03-21T00:16:36Z

← Older revision		Revision as of 00:16, 21 March 2024
Line 13:		Line 13:
	\|- share/fcitx5		\|- share/fcitx5
	\| \|		\| \|
	\| \|- ~~addons~~/[addon name].conf		\| \|- addon/[addon name].conf
	\| \|- inputmethod/[input method name 1].conf		\| \|- inputmethod/[input method name 1].conf
	\| \| ...		\| \| ...

Matrikslee: Marked this version for translation

2023-04-19T03:11:08Z

Marked this version for translation

Show changes

Weng Xuetian: /* Implement Input Method logic */

2022-07-01T16:16:47Z

Implement Input Method logic

← Older revision		Revision as of 16:16, 1 July 2022
Line 264:		Line 264:

	You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/b9b047abb46fa0f9c42a0be82941b65b35b277eb second commit] in the github.		You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/b9b047abb46fa0f9c42a0be82941b65b35b277eb second commit] in the github.

			== Store the state for different input contexts ==
			Fcitx allows different input context to held a different state. The state usually refers to the partially typed text and all other associated data structures. In Quwei case, the state is the digits that user already typed. To represent this, Fcitx provides a convenient class [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputBuffer.html InputBuffer] to allow engine to use this class conveniently to edit the internal state. In order to automatically construct the state when an input context getting constructed, Fcitx provides a framework called InputContextProperty. In order to use this, you first need to register a factory class to [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputContextManager.html InputContextManager], via registerProperty. Each property need to have a global unique name. The name can be something human-understandable. In Quwei case, I just use "quweiState". The benefit of using a nicer name is just in case you're developing something cross addon (Another addon need to access certain internal state of this addon), you can use this common name to load it in a different addon. If you do not need access from outside, the name does not really matter.

			The factory class comes with a handy C++ template, [https://codedocs.xyz/fcitx/fcitx5/group__FcitxCore.html#ga9e60042d1f671a6fa31ea04bb4961ec9 FactoryFor]. This is actually an type alias to [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1LambdaInputContextPropertyFactory.html LambdaInputContextPropertyFactory]. This class simply accepts a lambda function as the factory implementation. This can save you sometime from creating your own subclass of [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputContextPropertyFactory.html InputContextPropertyFactory].

			In order to get the state object from input context, you can simply use the factory object like this:

			<nowiki>
			auto *state = ic->propertyFor(&factory_);</nowiki>

			In certain cases, it is also possible to un-register the factory and re-register it again in order to "refresh" all the internal state.

	== Candidate List ==		== Candidate List ==

Weng Xuetian at 00:45, 23 November 2021

2021-11-23T00:45:12Z

← Older revision		Revision as of 00:45, 23 November 2021
Line 263:		Line 263:
	Quwei is basically typing 4 digit number of Quwei code. Quwei code can be treated as Qu code xx and Wei code yy. The mapping from Quwei to GB2312 is (0xA0 + Qu, 0xA0 + Wei). When user type 3 digits of Quwei, input method will display a candidate list of 10 possible character with given quwei prefix.		Quwei is basically typing 4 digit number of Quwei code. Quwei code can be treated as Qu code xx and Wei code yy. The mapping from Quwei to GB2312 is (0xA0 + Qu, 0xA0 + Wei). When user type 3 digits of Quwei, input method will display a candidate list of 10 possible character with given quwei prefix.

	You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/~~18e99e7c7db92751411006b122639ac2a5189f8b~~ second commit] in the github.		You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/b9b047abb46fa0f9c42a0be82941b65b35b277eb second commit] in the github.

	== Candidate List ==		== Candidate List ==
Line 285:		Line 285:

	= Reuse features from other addons =		= Reuse features from other addons =
	You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/~~6ee77a9f646fa14027940e16d95a91fa6ec42d2e~~ third commit] in the github.		You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/b01bf8c4344b50b496593b4d9cf8be49cd1ce9c2 third commit] in the github.

	Fcitx provides a mechanism to invoking functions from other addons without having the need of directly linking to them. And also some easy to use CMake macro to look up the addon dependencies.		Fcitx provides a mechanism to invoking functions from other addons without having the need of directly linking to them. And also some easy to use CMake macro to look up the addon dependencies.

Weng Xuetian: /* WIP */

2021-11-19T14:33:04Z

WIP

@@ Line 284: / Line 284: @@
 Also, a key event has 3 different form of the Key objects. Normally a input method engine may only want to consider only the key() property. origKey() and rawKey() properties are less used. Key property is in a normalized form of key event. That removes "Shift" modifier for certain cases, which makes it easier to handle by the input method engine. For example, upper case A produced by Shift+A and Capslocked A will be the same after normalization. You may refer to the implementation to learn about how this normalization works.
-= WIP =
+= Reuse features from other addons =
 </translate>

Weng Xuetian: /* Implement Input Method logic */

2021-11-19T14:08:40Z

Implement Input Method logic

← Older revision		Revision as of 14:08, 19 November 2021
Line 263:		Line 263:
	Quwei is basically typing 4 digit number of Quwei code. Quwei code can be treated as Qu code xx and Wei code yy. The mapping from Quwei to GB2312 is (0xA0 + Qu, 0xA0 + Wei). When user type 3 digits of Quwei, input method will display a candidate list of 10 possible character with given quwei prefix.		Quwei is basically typing 4 digit number of Quwei code. Quwei code can be treated as Qu code xx and Wei code yy. The mapping from Quwei to GB2312 is (0xA0 + Qu, 0xA0 + Wei). When user type 3 digits of Quwei, input method will display a candidate list of 10 possible character with given quwei prefix.

	You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/~~02c32b07e47e0e75db4f248dbb33c31137d8df74~~ second commit] in the github.		You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/18e99e7c7db92751411006b122639ac2a5189f8b second commit] in the github.

	== Candidate List ==		== Candidate List ==

Weng Xuetian: /* Implement Input Method logic */

2021-11-19T14:08:20Z

Implement Input Method logic

← Older revision		Revision as of 14:08, 19 November 2021
Line 262:		Line 262:
	= Implement Input Method logic =		= Implement Input Method logic =
	Quwei is basically typing 4 digit number of Quwei code. Quwei code can be treated as Qu code xx and Wei code yy. The mapping from Quwei to GB2312 is (0xA0 + Qu, 0xA0 + Wei). When user type 3 digits of Quwei, input method will display a candidate list of 10 possible character with given quwei prefix.		Quwei is basically typing 4 digit number of Quwei code. Quwei code can be treated as Qu code xx and Wei code yy. The mapping from Quwei to GB2312 is (0xA0 + Qu, 0xA0 + Wei). When user type 3 digits of Quwei, input method will display a candidate list of 10 possible character with given quwei prefix.

			You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/02c32b07e47e0e75db4f248dbb33c31137d8df74 second commit] in the github.

	== Candidate List ==		== Candidate List ==

Weng Xuetian: /* Basic implementation of InputMethodEngine */

2021-11-19T14:08:01Z

Basic implementation of InputMethodEngine

← Older revision		Revision as of 14:08, 19 November 2021
Line 171:		Line 171:

	== Basic implementation of InputMethodEngine ==		== Basic implementation of InputMethodEngine ==
			You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/02c32b07e47e0e75db4f248dbb33c31137d8df74 first commit] in the github.

	Version 1 of quwei.h		Version 1 of quwei.h

Weng Xuetian: /* Basic implementation of InputMethodEngine */

2021-11-19T14:07:07Z

Basic implementation of InputMethodEngine

@@ Line 258: / Line 258: @@
 So you know your input method engine is now working.
 = WIP =
 </translate>

← Older revision		Revision as of 00:16, 21 March 2024
Line 13:		Line 13:
	\|- share/fcitx5		\|- share/fcitx5
	\| \|		\| \|
	\| \|- ~~addons~~/[addon name].conf		\| \|- addon/[addon name].conf
	\| \|- inputmethod/[input method name 1].conf		\| \|- inputmethod/[input method name 1].conf
	\| \| ...		\| \| ...