API of uim

libuim contains following two types functionality
 (1)uim core
 (2)uim helper
uim core handles key events, mode switching, input method
enumeration, candidate lookup and so on. On the other hand,
uim helper handles status shareing on the desktop.

Core Library
 Functions
  uim_init()
  uim_create_context()
  uim_release_context()
  uim_reset_context()
  uim_set_preedit_cb()
  uim_get_nr_im()
  uim_get_im_name()
  uim_get_im_language()
  uim_get_im_encoding()
  uim_press_key()
  uim_release_key()
  uim_get_nr_modes()
  uim_get_mode_name()
  uim_set_mode_list_update_cb()
  uim_prop_list_update()
  uim_prop_label_update()
  uim_set_prop_list_update_cb()
  uim_set_prop_label_update_cb()
  uim_prop_activate()
  uim_get_current_mode()
  uim_set_mode()
  uim_set_mode_cb()
  uim_set_candidate_cb()
  uim_get_candidate()
  uim_get_candidate_index()
  uim_set_candidate_index()
Helper Library
  uim_helper_init_client_fd()
  uim_helper_close_client_fd();
  uim_helper_client_focus_in();
  uim_helper_client_focus_out();
  uim_helper_client_get_prop_list()
  uim_helper_read_proc()
  uim_helper_get_message()
  uim_helper_send_message()


--------------------------------functions--------------------------------
(note)
 Callback functions can be called asynchronously. However,
 they can not be called if other callback function is running.


int uim_init(void)
 arguments: void
 return value: 0 on success, otherwise -1
 description:
  Initialize uim library.
  Initialize and allocate resources to start input.
  This function must be called before any other uim functions
  are called. If this function is called when uim is already
  initialized, the call has no effect.


void uim_quit(void)
 arguments: void
 return value: void
 description:
  Finalize uim library. Free all resources allocated by uim.


uim_context uim_create_context(void *ptr, char *enc,
                               char *lang, char *engine,
                               struct uim_code_converter *conv,
                               void (*commit_cb)(void *ptr, char *str))
 arguments: ptr
            enc
            lang
            engine
            conv
            commit_cb
 return value: uim_context
 desctiption:
  Create input context.
  *return value: newly created context
  *[ptr] is a cookie value which is passed as an argument of uim's
   callback functions.
  *[enc] name of client encoding, say "UTF-8"
  *[lang],[engine] is used to specify appropriate input method
   tied to returning input context. Currently selected input
   method is used if you specify both as NULL.
  *[conv] is a character code converter. Say 'uim_iconv' or place your
   own platform-specific, preferable implementation. See struct
   uim_code_converter.
  *[commit_cb] is a callback function. It is called when there
   comes some string to commit. 1st argument of this callback
   function is the value passed by the uim_create_context call.
   2nd argument is the string commited.


void uim_release_context(uim_context uc)
 arguments: uc
 return value: void
 description:
  Release input context.
 *[uc] context to release


void uim_reset_context(uim_context uc)
 arguments: uc
 return value: void
 description:
  Reset input context.
 *[uc] context to reset
 Pending string might be commited and preedit
 string might be erased. (Not yet implemented so)


void uim_set_preedit_cb(uim_context uc,
                        void (*clear_cb)(void *ptr),
                        void (*pushback_cb)(void *ptr, int attr, char *str),
                        void (*update_cb)(void *ptr));
 arguments: uc
            clear_cb
            pushback_cb
            update_cb
 return value: void
 description:
  Set callback functions to be called when the preedit string changes.
 *[clear_cb]
 *[pushback_cb]
 *[update_cb]
 Preedit string is passed to applications by sequential calls of
 pushback_cb, between the call of clear_cb and update_cb

void uim_press_key(uim_context uc, int key, int state);
 arguments: uc
            key
            state
 return value: int
 description:
  Send key press event to uim context.
  Return value is not 0, if uim does not process the key event.

int
uim_release_key(uim_context uc, int key, int state);
 arguments: uc
            key
            state
 return value: int
 description:
  Send key release event to uim context. In some environments like
  ttys, release event can not be processed. You do not have to call
  this function.
  Return value is not 0, if uim does not process the key event.
