NAME

       Input_Method_(basic) - API for Input method.

   Data Structures
       struct MInputDriver
           Structure of input method driver.
       struct MInputMethod
           Structure of input method.
       struct MInputContext
           Structure of input context.

   Typedefs
       typedef void(* MInputCallbackFunc )(MInputContext *ic, MSymbol command)
           Type of input method callback functions.

   Enumerations
       enum MInputCandidatesChanged { MINPUT_CANDIDATES_LIST_CHANGED =  1,
           MINPUT_CANDIDATES_INDEX_CHANGED =  2, MINPUT_CANDIDATES_SHOW_CHANGED =  4,
           MINPUT_CANDIDATES_CHANGED_MAX }
           Bit-masks to specify how candidates of input method is changed.

   Variables
       MSymbol Minput_method
           Symbol whose name is 'input-method'.
       MInputDriver minput_default_driver
           The default driver for internal input methods.
       MInputDriver * minput_driver
           The driver for internal input methods.
       MSymbol Minput_driver

   Variables: Predefined symbols for callback commands.
        These are the predefined symbols that are used as the COMMAND argument of callback
       functions of an input method driver (see MInputDriver::callback_list).

       Most of them do not require extra argument nor return any value; exceptions are these:

       Minput_get_surrounding_text: When a callback function assigned for this command is called,
       the first element of MInputContext::plist has key Minteger and the value specifies which
       portion of the surrounding text should be retrieved. If the value is positive, it
       specifies the number of characters following the current cursor position. If the value is
       negative, the absolute value specifies the number of characters preceding the current
       cursor position. If the value is zero, it means that the caller just wants to know if the
       surrounding text is currently supported or not.

       If the surrounding text is currently supported, the callback function must set the key of
       this element to Mtext and the value to the retrieved M-text. The length of the M-text may
       be shorter than the requested number of characters, if the available text is not that
       long. The length can be zero in the worst case. Or, the length may be longer if an
       application thinks it is more efficient to return that length.

       If the surrounding text is not currently supported, the callback function should return
       without changing the first element of MInputContext::plist.

       Minput_delete_surrounding_text: When a callback function assigned for this command is
       called, the first element of MInputContext::plist has key Minteger and the value specifies
       which portion of the surrounding text should be deleted in the same way as the case of
       Minput_get_surrounding_text. The callback function must delete the specified text. It
       should not alter MInputContext::plist.
       MSymbol Minput_preedit_start
       MSymbol Minput_preedit_done
       MSymbol Minput_preedit_draw
       MSymbol Minput_status_start
       MSymbol Minput_status_done
       MSymbol Minput_status_draw
       MSymbol Minput_candidates_start
       MSymbol Minput_candidates_done
       MSymbol Minput_candidates_draw
       MSymbol Minput_set_spot
       MSymbol Minput_toggle
       MSymbol Minput_reset
       MSymbol Minput_get_surrounding_text
       MSymbol Minput_delete_surrounding_text

   Variables: Predefined symbols for special input events.
        These are the predefined symbols that are used as the KEY argument of minput_filter().
       MSymbol Minput_focus_out
       MSymbol Minput_focus_in
       MSymbol Minput_focus_move

   Variables: Predefined symbols used in input method information.
       MSymbol Minherited
       MSymbol Mcustomized
       MSymbol Mconfigured

   Functions
       MInputMethod * minput_open_im (MSymbol language, MSymbol name, void *arg)
           Open an input method.
       void minput_close_im (MInputMethod *im)
           Close an input method.
       MInputContext * minput_create_ic (MInputMethod *im, void *arg)
           Create an input context.
       void minput_destroy_ic (MInputContext *ic)
           Destroy an input context.
       int minput_filter (MInputContext *ic, MSymbol key, void *arg)
           Filter an input key.
       int minput_lookup (MInputContext *ic, MSymbol key, void *arg, MText *mt)
           Look up a text produced in the input context.
       void minput_set_spot (MInputContext *ic, int x, int y, int ascent, int descent, int
           fontsize, MText *mt, int pos)
           Set the spot of the input context.
       void minput_toggle (MInputContext *ic)
           Toggle input method.
       void minput_reset_ic (MInputContext *ic)
           Reset an input context.
       MPlist * minput_get_title_icon (MSymbol language, MSymbol name)
           Get title and icon filename of an input method.
       MText * minput_get_description (MSymbol language, MSymbol name)
           Get description text of an input method.
       MPlist * minput_get_command (MSymbol language, MSymbol name, MSymbol command)
           Get information about input method command(s).
       int minput_config_command (MSymbol language, MSymbol name, MSymbol command, MPlist
           *keyseqlist)
           Configure the key sequence of an input method command.
       MPlist * minput_get_variable (MSymbol language, MSymbol name, MSymbol variable)
           Get information about input method variable(s).
       int minput_config_variable (MSymbol language, MSymbol name, MSymbol variable, MPlist
           *value)
           Configure the value of an input method variable.
       char * minput_config_file ()
           Get the name of per-user customization file.
       int minput_save_config (void)
           Save configurations in per-user customization file.

   Obsolete functions
       MPlist * minput_get_variables (MSymbol language, MSymbol name)
           Get a list of variables of an input method (obsolete).
       int minput_set_variable (MSymbol language, MSymbol name, MSymbol variable, void *value)
           Set the initial value of an input method variable.
       MPlist * minput_get_commands (MSymbol language, MSymbol name)
           Get information about input method commands.
       int minput_assign_command_keys (MSymbol language, MSymbol name, MSymbol command, MPlist
           *keyseq)
           Assign a key sequence to an input method command (obsolete).
       int minput_callback (MInputContext *ic, MSymbol command)
           Call a callback function.

Detailed Description

       API for Input method.

       An input method is an object to enable inputting various characters. An input method is
       identified by a pair of symbols, LANGUAGE and NAME. This pair decides an input method
       driver of the input method. An input method driver is a set of functions for handling the
       input method. There are two kinds of input methods; internal one and foreign one.

       • Internal Input Method
       An internal input method has non Mnil LANGUAGE, and its body is defined in the m17n
       database by the tag <Minput_method, LANGUAGE, NAME>. For this kind of input methods, the
       m17n library uses two predefined input method drivers, one for CUI use and the other for
       GUI use. Those drivers utilize the input processing engine provided by the m17n library
       itself. The m17n database may provide input methods that are not limited to a specific
       language. The database uses Mt as LANGUAGE of those input methods.
       An internal input method accepts an input key which is a symbol associated with an input
       event. As there is no way for the m17n library to know how input events are represented in
       an application program, an application programmer has to convert an input event to an
       input key by himself. See the documentation of the function minput_event_to_key() for the
       detail.
       • Foreign Input Method
       A foreign input method has Mnil LANGUAGE, and its body is defined in an external resource
       (e.g. XIM of X Window System). For this kind of input methods, the symbol NAME must have a
       property of key Minput_driver, and the value must be a pointer to an input method driver.
       Therefore, by preparing a proper driver, any kind of input method can be treated in the
       framework of the m17n library.
       For convenience, the m17n-X library provides an input method driver that enables the input
       style of OverTheSpot for XIM, and stores Minput_driver property of the symbol Mxim with a
       pointer to the driver. See the documentation of m17n GUI API for the detail.
       PROCESSING FLOW
       The typical processing flow of handling an input method is:
       • open an input method
       • create an input context for the input method
       • filter an input key
       • look up a produced text in the input context

Data Structure Documentation

   MInputDriver
       FIELD DOCUMENTATION:
       int(* MInputDriver::open_im)(MInputMethod *im)
       Open an input method. This function opens the input method im. It is called from the
       function minput_open_im() after all member of im but <info> set. If opening im succeeds,
       it returns 0. Otherwise, it returns -1. The function can setup im->info to keep various
       information that is referred by the other driver functions.
       void(* MInputDriver::close_im)(MInputMethod *im)
       Close an input method. This function closes the input method im. It is called from the
       function minput_close_im(). It frees all memory allocated for im->info (if any) after
       finishing all the tasks of closing the input method. But, the other members of im should
       not be touched.
       int(* MInputDriver::create_ic)(MInputContext *ic)
       Create an input context. This function creates the input context ic. It is called from the
       function minput_create_ic() after all members of ic but <info> are set. If creating ic
       succeeds, it returns 0. Otherwise, it returns -1. The function can setup ic->info to keep
       various information that is referred by the other driver functions.
       void(* MInputDriver::destroy_ic)(MInputContext *ic)
       Destroy an input context. This function is called from the function minput_destroy_ic()
       and destroys the input context ic. It frees all memory allocated for ic->info (if any)
       after finishing all the tasks of destroying the input method. But, the other members of ic
       should not be touched.
       int(* MInputDriver::filter)(MInputContext *ic, MSymbol key, void *arg)
       Filter an input key. This function is called from the function minput_filter() and filters
       an input key. key and arg are the same as what given to minput_filter().
       The task of the function is to handle key, update the internal state of ic. If key is
       absorbed by the input method and no text is produced, it returns 1. Otherwise, it returns
       0.
       It may update ic->status, ic->preedit, ic->cursor_pos, ic->ncandidates, ic->candidates,
       and ic->produced if that is necessary for the member <callback>.
       The meaning of arg depends on the input method river. See the documentation of
       minput_default_driver and minput_gui_driver for instance.
       int(* MInputDriver::lookup)(MInputContext *ic, MSymbol key, void *arg, MText *mt)
       Lookup a produced text in an input context. It is called from the function minput_lookup()
       and looks up a produced text in the input context ic. This function concatenate a text
       produced by the input key key (if any) to M-text mt. If key was correctly handled by the
       input method of ic, it returns 0. Otherwise, it returns 1.
       The meaning of arg depends on the input method driver. See the documentation of
       minput_default_driver and minput_gui_driver for instance.
       MPlist* MInputDriver::callback_list
       List of callback functions. List of callback functions. Keys are one of
       Minput_preedit_start, Minput_preedit_draw, Minput_preedit_done, Minput_status_start,
       Minput_status_draw, Minput_status_done, Minput_candidates_start, Minput_candidates_draw,
       Minput_candidates_done, Minput_set_spot, Minput_toggle, Minput_reset,
       Minput_get_surrounding_text, Minput_delete_surrounding_text. Values are functions of type
       MInputCallbackFunc.

   MInputMethod
       FIELD DOCUMENTATION:
       MSymbol MInputMethod::language
       MSymbol MInputMethod::name
       MInputDriver MInputMethod::driver
       void* MInputMethod::arg
       void* MInputMethod::info

   MInputContext
       FIELD DOCUMENTATION:
       MInputMethod* MInputContext::im
       MText* MInputContext::produced
       void* MInputContext::arg
       int MInputContext::active
       int MInputContext::x
       int MInputContext::y
       int MInputContext::ascent
       int MInputContext::descent
       int MInputContext::fontsize
       MText* MInputContext::mt
       int MInputContext::pos
       struct { ... }   MInputContext::spot
       void* MInputContext::info
       MText* MInputContext::status
       int MInputContext::status_changed
       MText* MInputContext::preedit
       int MInputContext::preedit_changed
       int MInputContext::cursor_pos
       int MInputContext::cursor_pos_changed
       MPlist* MInputContext::candidate_list
       int MInputContext::candidate_index
       int MInputContext::candidate_from
       int MInputContext::candidate_to
       int MInputContext::candidate_show
       int MInputContext::candidates_changed
       MPlist* MInputContext::plist

Typedef Documentation

   typedef void(* MInputCallbackFunc)(MInputContext *ic, MSymbol command)
       Type of input method callback functions. This is the type of callback functions called
       from input method drivers. ic is a pointer to an input context, command is a name of
       callback for which the function is called.

Enumeration Type Documentation

   enum MInputCandidatesChanged
       Bit-masks to specify how candidates of input method is changed.
       Enumerator:
       MINPUT_CANDIDATES_LIST_CHANGED
       MINPUT_CANDIDATES_INDEX_CHANGED
       MINPUT_CANDIDATES_SHOW_CHANGED
       MINPUT_CANDIDATES_CHANGED_MAX

Variable Documentation

   MSymbol Minput_method
       Symbol whose name is 'input-method'.
   MSymbol Minput_preedit_start
   MSymbol Minput_preedit_done
   MSymbol Minput_preedit_draw
   MSymbol Minput_status_start
   MSymbol Minput_status_done
   MSymbol Minput_status_draw
   MSymbol Minput_candidates_start
   MSymbol Minput_candidates_done
   MSymbol Minput_candidates_draw
   MSymbol Minput_set_spot
   MSymbol Minput_toggle
   MSymbol Minput_reset
   MSymbol Minput_get_surrounding_text
   MSymbol Minput_delete_surrounding_text
   MSymbol Minput_focus_out
   MSymbol Minput_focus_in
   MSymbol Minput_focus_move
   MSymbol Minherited These are the predefined symbols describing status of input method command
       and variable, and are used in a return value of minput_get_command() and
       minput_get_variable().
   MSymbol Mcustomized
   MSymbol Mconfigured
   MInputDriver minput_default_driver
       The default driver for internal input methods. The variable minput_default_driver is the
       default driver for internal input methods.
       The member MInputDriver::open_im() searches the m17n database for an input method that
       matches the tag < Minput_method, language, name> and loads it.
       The member MInputDriver::callback_list() is NULL. Thus, it is programmers responsibility
       to set it to a plist of proper callback functions. Otherwise, no feedback information
       (e.g. preedit text) can be shown to users.
       The macro M17N_INIT() sets the variable minput_driver to the pointer to this driver so
       that all internal input methods use it.
       Therefore, unless minput_driver is set differently, the driver dependent arguments arg of
       the functions whose name begins with 'minput_' are all ignored.
   MInputDriver* minput_driver
       The driver for internal input methods. The variable minput_driver is a pointer to the
       input method driver that is used by internal input methods. The macro M17N_INIT()
       initializes it to a pointer to minput_default_driver if <m17n.h> is included.
   MSymbol Minput_driver The variable Minput_driver is a symbol for a foreign input method. See
       foreign input method for the detail.

Author

       Generated automatically by Doxygen for The m17n Library from the source code.

Function Documentation

   MPlist* minput_get_variables (MSymbol language, MSymbol name)
       Get a list of variables of an input method (obsolete). This function is obsolete. Use
       minput_get_variable() instead.
       The minput_get_variables() function returns a plist (MPlist) of variables used to control
       the behavior of the input method specified by language and name. The plist is well-formed
       (Property List) of the following format:
           (VARNAME (DOC-MTEXT DEFAULT-VALUE [ VALUE ... ] )
            VARNAME (DOC-MTEXT DEFAULT-VALUE [ VALUE ... ] )
            ...)
       VARNAME is a symbol representing the variable name.
       DOC-MTEXT is an M-text describing the variable.
       DEFAULT-VALUE is the default value of the variable. It is a symbol, integer, or M-text.
       VALUEs (if any) specifies the possible values of the variable. If DEFAULT-VALUE is an
       integer, VALUE may be a plist (FROM TO), where FROM and TO specifies a range of possible
       values.
       For instance, suppose an input method has the variables:
       • name:intvar, description:'value is an integer', initial value:0, value-range:0..3,10,20
       • name:symvar, description:'value is a symbol', initial value:nil, value-range:a, b, c,
         nil
       • name:txtvar, description:'value is an M-text', initial value:empty text, no value-range
         (i.e. any text)
       Then, the returned plist is as follows.
           (intvar ("value is an integer" 0 (0 3) 10 20)
            symvar ("value is a symbol" nil a b c nil)
            txtvar ("value is an M-text" ""))
       RETURN VALUE
           If the input method uses any variables, a pointer to MPlist is returned. As the plist
           is kept in the library, the caller must not modify nor free it. If the input method
           does not use any variable, NULL is returned.
   int minput_set_variable (MSymbol language, MSymbol name, MSymbol variable, void * value)
       Set the initial value of an input method variable. The minput_set_variable() function sets
       the initial value of input method variable variable to value for the input method
       specified by language and name.
       By default, the initial value is 0.
       This setting gets effective in a newly opened input method.
       RETURN VALUE
           If the operation was successful, 0 is returned. Otherwise -1 is returned, and
           merror_code is set to MERROR_IM.
   MPlist* minput_get_commands (MSymbol language, MSymbol name)
       Get information about input method commands. The minput_get_commands() function returns
       information about input method commands of the input method specified by language and
       name. An input method command is a pseudo key event to which one or more actual input key
       sequences are assigned.
       There are two kinds of commands, global and local. Global commands are used by multiple
       input methods for the same purpose, and have global key assignments. Local commands are
       used only by a specific input method, and have only local key assignments.
       Each input method may locally change key assignments for global commands. The global key
       assignment for a global command is effective only when the current input method does not
       have local key assignments for that command.
       If name is Mnil, information about global commands is returned. In this case language is
       ignored.
       If name is not Mnil, information about those commands that have local key assignments in
       the input method specified by language and name is returned.
       RETURN VALUE
           If no input method commands are found, this function returns NULL.
       Otherwise, a pointer to a plist is returned. The key of each element in the plist is a
       symbol representing a command, and the value is a plist of the form COMMAND-INFO described
       below.
       The first element of COMMAND-INFO has the key Mtext, and the value is an M-text describing
       the command.
       If there are no more elements, that means no key sequences are assigned to the command.
       Otherwise, each of the remaining elements has the key Mplist, and the value is a plist
       whose keys are Msymbol and values are symbols representing input keys, which are currently
       assigned to the command.
       As the returned plist is kept in the library, the caller must not modify nor free it.
   int minput_assign_command_keys (MSymbol language, MSymbol name, MSymbol command, MPlist *
       keyseq)
       Assign a key sequence to an input method command (obsolete). This function is obsolete.
       Use minput_config_command() instead.
       The minput_assign_command_keys() function assigns input key sequence keyseq to input
       method command command for the input method specified by language and name. If name is
       Mnil, the key sequence is assigned globally no matter what language is. Otherwise the key
       sequence is assigned locally.
       Each element of keyseq must have the key msymbol and the value must be a symbol
       representing an input key.
       keyseq may be NULL, in which case, all assignments are deleted globally or locally.
       This assignment gets effective in a newly opened input method.
       RETURN VALUE
           If the operation was successful, 0 is returned. Otherwise -1 is returned, and
           merror_code is set to MERROR_IM.
   int minput_callback (MInputContext * ic, MSymbol command)
       Call a callback function. The minput_callback() functions calls a callback function
       command assigned for the input context ic. The caller must set specific elements in
       ic->plist if the callback function requires.
       RETURN VALUE
           If there exists a specified callback function, 0 is returned. Otherwise -1 is
           returned. By side effects, ic->plist may be modified.

COPYRIGHT

       Copyright (C) 2001 Information-technology Promotion Agency (IPA)
       Copyright (C) 2001-2011 National Institute of Advanced Industrial Science and Technology
       (AIST)
       Permission is granted to copy, distribute and/or modify this document under the terms of
       the GNU Free Documentation License <http://www.gnu.org/licenses/fdl.html>.