miniChinput Internal

Table of Contents:
1. Introduction
2. History
3. i18n issue
3. XIM issue
4. Architectual of miniChinput
5. How chinput interface with IMdkit
6. How chinput interfacw with Unicon
7. References

Introduction:
	This document aims on illustrated different implementation aspect of miniChinput (Chinese 2000 version). miniChinput (vC2K) is released under GPL, all the source code, and this table are also released under GPL.

History:
	miniChinput (vC2K) is a derived version from miniChinput-0.0.2 which in turn is derived from Chinput-0.0.3. Due to this relation, these three software share a large portion of source code, and almost a same architecture. In the following document, miniChinput (vC2K), miniChinput and chinput are used interchangably. Information which is dedicated to miniChinput (vC2K) will be specified.

i18n issue:
	i18n refers to internationalization. It refers to a process, that is develop your program following a few common practice and greatly minimized the cost for translation a program from a language to the other one (For example, translation a program with English interface to a Chinese interface).
	At the moment of this writing, the i18n environment is almost complete. General character and encoding processing is handled by glibc. Under X Windows, the output of characters is handled under a X Output Method protocol, while, X Input Method Protocol is responsible for X Input.

XIM issue:
	The XIM Protocol froom X.org is technical specification. It can serves as a guidline for all XIM input server developer.
	[TODO: A brief introduction to XIM Protocol]

Architecture of miniChinput:
	miniChinput is actually interface with two library. One of the library is called IMdkit, which is used to handle all lower level XIM protocol processing with Xlib. The another one is called Unicon. Where the core source code of chinput is responsible to doing to control work, handling request from IMdkit, parse incoming char, pass relevent char to Unicon, get result from unicon, and display it.
	IMdkit is a library develop Hidetoshi Tajima. As the XIM protocol is complex enough, using IMdkit to handle all protocol dependent details can save a lot. Inside the source tree of chinput, IMdkit is located under (miniChinput-SRC/src/IMdkit/lib/) .
	Unicon is originally a Input Method server, which is developed by Turbo Linux. However, chinput only used a part of the functions from it. By calling initialization function, Unicon will load respective input modules, (e.g. TL_hzinput.so). Originally, Unicon is a seperate package, but started from miniChinput, and to now, the miniChinput (vC2K), the Source of unicon is located under the source tree of miniChinput (miniChinput-SRC/unicon/)

How chinput interface with IMdkit:
	In the initialization phrase, chinput will call IMOpenIM (), with a list of arguments. IMdkit will then register the IM Server (chinput in our case) with X. One of the most important argument is 'IMProtocolHandler', chinput will pass a function pointer, which is pointing to ChinputProtoHandler (), as the value of this argument. Obviously, this is a callback registration. Whenever a X event is got by IMdkit, and should be handled by IM Server, IMdkit will pass the XEvent to IM Server through this callback function. Hence, in xim.c, you can see that, ChinputProtoHandler () is being a dispatcher for various XIM related event.

There is some interesting point which is worth mentioned. Inside ChinputProtoHandler (), different kind of XIM event is dispatched by its type. By observing the behaviour inside this function, you can observe the interacting between the IM Server and different X client program. For example, when you open a xterm, you will the following sequences:
	1. XIM_OPEN
	2. XIM_CREATE_IC
	3. XIM_SET_IC_VALUES
	4. XIM_SET_IC_FOCUS
In other words, when we catch the XIM_OPEN event, we should initialize the data for a new XIM client. For a XIM_CREATE_IC, we should initialize the data for an Input Context for this XIM client. For the XIM_SET_IC_VALUES event, it is a generic event for the XIM client to comunicate with XIM server, in order to set some settings for it. The XIM_SET_IC_FOCUS, is a event which is notifying the input context of client is under 'focus' and show, IM server should start its work !!

	However, the complexity of the XIM protocol and the variety of implementation in different GUI tookit makes the thing even more complicated. For example, gvim may issue a XIM_RESET_IC instead of XIM_SET_IC_VALUES, and the XIM_SET_IC_FOCUS. Hence if we want to implement a better XIM server, we have to doing more comprehensive testing on different GUI toolkit and some application which doesn't depends on GUI toolkit (those written with native xlib).

How do chinput interface with Unicon:
	Unicon is a generic input server, in other words, it is not dedicated for chinput, or XIM. It is used as the IM server for console also, in Turbo Linux. Unicon is implemented in C++, which will load different input modules by dlopen () system calls.

	At the initialization phrase, chinput will call a LibOpen () and IMM_OpenClient () to initialize the connection with Uncion. Unicon will do the preperation works at this time. While all the things are ready, chinput will call different Unicon function to do the regular Input Method works. The following is a complete listing.
	1. LibOpen ()
	2. LibRelease ()
	3. IMM_OpenClient ()
	4. IMM_OpenInput ()
	5. IMM_SetInputMode ()
	6. IMM_ConfigInputArea
	7. IMM_FlushUserPhrase ()
	8. IMM_GetInputDisplay ()
	9. IMM_GetSelectDisplay ()
	10. IMM_KeyFilter ()
	11. IMM_CloseInput ()
	12. IMM_CloseClient ()
The function LibOpen (), LibRelease (), IMM_OpenClient (), IMM_CloseClient (), IMM_OpenInput () and IMM_CloseInput () is responsible for starting and closing unicon, and initialization for different Input Modules.  IMM_SetInputMode () and IMM_ConfigInputArea () is also at initialization phrase to set the attribute of Unicon.

The most important functions among the listing are IMM_KeyFilter (), IMM_GetInputDisplay (), IMM_GetSelectDisplay (). IMM_KeyFilter () is used to parse each character, and returning a status code to indicate the result of translation.

IMM_GetInputDisplay () is used to query a Input Method module, what should be displayed on the input bar. Many different input method is using different alphabetic key to represent different language symbol. For example, in CangJie, 'a' should be map to '', and 'b' should be map to ''. This kind of work is also done by input modules, chinput can query this by IMM_GetInputDisplay ().

IMM_GetSelectDisplay () server a similar function. Whenever a user press a key, and chinput forward the key to unicon. In many cases, more than one choice may be available for the current input status. This especially true for Simplex or Phone input method. To provide the choice for user to select words, chinput use IMM_GetSelectDisplay () to query Unicon that, what is available for user to choose??

-Preferences-
=============
1.	XIM Protocol Specification
	http://www.x.org
