Terminal Input Interface 0.4
Young Chol Song (nskystars at yahoo dot com)

README, 4 June 2004

***** Description *****

Terminal Input Interface(TII) simplifies the process of including many languages by combining various input methods into one interface, supporting the input of many languages using just a couple of pre-defined functions.

TII supports IIIMF(using IIIMCF), so you can use the same IM X-windows uses on the terminal. As of now, TII only supports IIIMF (which itself supports numerous input methods), but it is easily extensible and in the future will include more input methods, many which are not included in IIIMF.

Future versions (hopefully) will come with a terminal input program, which will enable you to input various languages directly from your linux console/terminal.


***** Downloading & Installing im-sdk *****

You need im-sdk source to compile the test programs. (I might be wrong here.) You can get the latest im-sdk source using subversion on the IIIMF website. I also have some tar.gz'd snapshot versions of im-sdk. (Go to http://kldp.net/projects/hangul-jfbterm and click on Downloads, and under the im-sdk section.)

First try compile/installing everything, but if you're unsuccessful like me, go into the subdirectories and try compiling and installing as much as you can. (Try at least the 'iiimsf,' 'leif,' and 'lib' subdirectories, and copy the include files into '/usr/local/include'.)


***** Running the test program *****

After you've succefully compiled and installed im-sdk :), return to this directory and type:

# make IIIMF_SRC=/path/to/im-sdk/src

where '/path/to/im-sdk/src' is the path to your im-sdk source. For example I'd type 'make IIIMF_SRC=/usr/local/src/im-sdk/trunk'

Run 'htt_server' (usually in '/usr/lib/im/htt_server'). Run the test program. If everything went OK, you'll be able to see many lines showing the status of the IM. (You'll need a terminal that supports Korean output to actually see the characters printed in the test program.)


***** Using TII in YOUR programs *****

Now that you've got the test programs to work, let's see how you can incorperate them into your programs. (Refer back to the test program) 


1. The following files need to be included as your headers

> #include "tii.h"
> #include "global.h"

2. Check the 'global.h' file

> #define TII_COMMIT commit_handler
> #define TII_PREEDIT preedit_handler
> #define TII_STATUS status_handler
> #define TII_LOOKUP lookup_handler

xxxxx_handler is the function that handles output from IM. Whenever IM has a change in its status, TII calls the corresponding function with its changed status being the first argument of the function.

For example, if the IM wants to commit a character, it calls TII_COMMIT, which is defined as commit_handler (you can change the function name) with the needs-to-be-commited character as its first argument. These functions are not already defined in TII; you must create them according to the needs of your program.

TII_LOOKUP will be supported in the next version(0.5) of TII.

3. Initialize TII

> IMList * im;
> tii_global_use_im("IM NAME"); /*
>				 * IM NAME can be a pre-defined non-IIIMF IM
>				 * name (look below at 'Adding more input...') 
>				 * or if not defined, automatically defaults
>				 * to a IIIMF LEIF name (hangul, CannaLE, ...)
>				 */
> im = tii_get_im(); 		/*
> 				 * tii_get_im recieves functions according to 
> 				 * values given in tii_global_use_im
> 				 */
> im->init();

4. Send a character through TII

> im->sendkey('KEY', SHIFT_STATE);

5. To finalize and exit TII

> im->exit();

6. Use the following options while compiling

> -DHAVE_CONFIG_H
> -DUSE_TII
> -I$(IIIMF_SRC)/lib/iiimp
> -I$(IIIMF_SRC)/include
> -liiimcf

$(IIIMF_SRC) is the location of your im-sdk source. Look at the Makefile for an example.

7. While executing your program

Make sure 'htt_server' is running.

8. More...

Take a look at 'test.c'.


***** Adding more input methods to TII *****

TII is very extensible so new input methods can be easily implemented with minimal change of code. To implement your input method, once you have your automata code, separate the code into three routines: initalization, key_send and finalization.

For example, let's say I have a 'sample' automata code, and I've separated it into 'tii_sample_init', 'tii_sample_sendkey', and 'tii_sample_exit'. In the file where those functions are defined, I'd add the following:

> #ifdef USE_TII
> IMList sample = {"sample",
>			tii_sample_init,
>			tii_sample_sendkey,
>			tii_sample_exit};
> #endif

Also, in the front of the file, I'd add the header 'tii.h' since I'm using 'struct IMList' and it's defined in that header file.

> #ifdef USE_TII
> #include "tii.h"
> #endif

Notice that I'm wrapping code with '#ifdef USE_TII', so I differentiate TII code from the regular automata code.

Next, I'll add my function collection to the list of input methods located in 'tii.c'

> ...
> extern IMList sample;
> IMList *input_methods[] = {
>	...
>	&sample,
>	NULL
> };

To use the newly added input method, include the following code during initalization.

> tii_global_use_im("sample");


***** TODO & Other stuff *****

1. Segfaults when encountered with errors; when htt_server is not running(while using IIIMF), or when it encounters unexpected problems. Process errors.

2. The interface is a lot more complicated than the initial plan. Simplify.

3. Implement TII_LOOKUP.

4. Include terminal input program using TII.

5. Add other non-IIIMF input methods (nabi, hanterm-xf, ...)
