m17nInputMethod_-_Input_Method_(ba - - API for Input method.

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

       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>.

Version 1.8.4                                    Mon Sep 25 2023                          m17nInputMethod(3m17n)

MInputDriver
       Structure of input method driver.

       FIELDDOCUMENTATION: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,MSymbolkey,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,MSymbolkey,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
       Structure of input method.

       FIELDDOCUMENTATION:MSymbolMInputMethod::language Which language this input method is for. The value is Mnil if the input
       method is foreign.

       MSymbolMInputMethod::name Name of the input method. If the input method is foreign, it must has a
       property of key Minput_driver and the value must be a pointer to a proper input method driver.

       MInputDriverMInputMethod::driverInputmethoddriveroftheinputmethod.void*MInputMethod::arg The argument given to minput_open_im().
       void*MInputMethod::info Pointer to extra information that <driver>.open_im() setups.

   MInputContext
       Structure of input context.

       FIELDDOCUMENTATION:MInputMethod*MInputContext::imBackwardpointertotheinputmethod.Itissetupbythefunctionminput_create_ic().MText*MInputContext::producedM-textproducedbytheinputmethod.Itissetupbythefunctionminput_filter().void*MInputContext::arg Argument given to the function minput_create_ic().
       intMInputContext::active Flag telling whether the input context is currently active or inactive. The
       value is set to 1 (active) when the input context is created. It is toggled by the function
       minput_toggle().

       intMInputContext::x X and Y coordinate of the spot.
       intMInputContext::yintMInputContext::ascent Ascent and descent pixels of the line of the spot.
       intMInputContext::descentintMInputContext::fontsize Font size for preedit text in 1/10 point.
       MText*MInputContext::mtM-textatthespot,orNULL.intMInputContext::pos Character position in <mt> at the spot.
       struct{...}MInputContext::spot Spot location and size of the input context.
       void*MInputContext::info The usage of the following members depends on the input method driver. The
       descriptions below are for the driver of an internal input method. They are set by the function
       <im>->driver.filter().
        Pointer to extra information that <im>->driver.create_ic() setups. It is used to record the internal
       state of the input context.

       MText*MInputContext::statusM-textdescribingthecurrentstatusoftheinputcontext.intMInputContext::status_changed The function <im>->driver.filter() sets the value to 1 when it changes
       <status>.

       MText*MInputContext::preeditM-textcontainingthecurrentpreedittext.Thefunction<im>->driver.filter()setsthevalue.intMInputContext::preedit_changed The function <im>->driver.filter() sets the value to 1 when it changes
       <preedit>.

       intMInputContext::cursor_pos Cursor position of <preedit>.
       intMInputContext::cursor_pos_changed The function <im>->driver.filter() sets the value to 1 when it
       changes <cursor_pos>.

       MPlist*MInputContext::candidate_listPlistofthecurrentcandidategroups.EachelementisanM-textoraplist.IfanelementisanM-text(i.e.thekeyisMtext),candidatesinthatgrouparecharactersintheM-text.Ifitisaplist(i.e.thekeyisMplist),eachelementisanM-text,andcandidatesinthatgrouparethoseM-texts.intMInputContext::candidate_index Index number of the currently selected candidate in all the
       candidates. The index of the first candidate is 0. If the number is 8, and the first candidate group
       contains 7 candidates, the currently selected candidate is the second element of the second candidate
       group.

       intMInputContext::candidate_from Start and the end positions of the preedit text where <candidate_list>
       corresponds to.

       intMInputContext::candidate_tointMInputContext::candidate_show Flag telling whether the current candidate group must be shown or not.
       The function <im>->driver.filter() sets the value to 1 when an input method required to show candidates,
       and sets the value to 0 otherwise.

       intMInputContext::candidates_changed The function <im>->driver.filter() sets the value to bitwise OR of
       enum MInputCandidatesChanged when it changed any of the above members (<candidate_XXX>), and sets the
       value to 0 otherwise.

       MPlist*MInputContext::plistPlistthatcanbefreelyusedby<im>->driverfunctions.Thedriverofinternalinputmethodusesittoexchangeextraargumentsandresultforcallbackfunctions.Thefunction<im>->driver.create_ic()setsthistoanemptyplist,andthefunction<im>->driver.destroy_ic()freesitbyusingm17n_object_unref().

       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

enumMInputCandidatesChanged
       Bit-masks to specify how candidates of input method is changed.

       EnumeratorMINPUT_CANDIDATES_LIST_CHANGEDMINPUT_CANDIDATES_INDEX_CHANGEDMINPUT_CANDIDATES_SHOW_CHANGEDMINPUT_CANDIDATES_CHANGED_MAX

MPlist*minput_get_variables(MSymbollanguage,MSymbolname)
       @brief 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 @b language and @b name.  The plist is @e well-formed
       (@ref m17nPlist) of the following format:

           (VARNAME (DOC-MTEXT DEFAULT-VALUE [ VALUE ... ] )
            VARNAME (DOC-MTEXT DEFAULT-VALUE [ VALUE ... ] )
            ...)

       @c VARNAME is a symbol representing the variable name.

       @c DOC-MTEXT is an M-text describing the variable.

       @c DEFAULT-VALUE is the default value of the variable.  It is a
       symbol, integer, or M-text.

       @c VALUEs (if any) specifies the possible values of the variable.
       If @c DEFAULT-VALUE is an integer, @c VALUE may be a plist (@c FROM
       @c TO), where @c FROM and @c TO specifies a range of possible
       values.

       For instance, suppose an input method has the variables:

       @li name:intvar, description:"value is an integer",
            initial value:0, value-range:0..3,10,20

       @li name:symvar, description:"value is a symbol",
            initial value:nil, value-range:a, b, c, nil

       @li 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" ""))

       @par 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, @c NULL is returned.

   intminput_set_variable(MSymbollanguage,MSymbolname,MSymbolvariable,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.
       RETURNVALUEIftheoperationwassuccessful,0isreturned.Otherwise-1isreturned,andmerror_codeissettoMERROR_IM.MPlist*minput_get_commands(MSymbollanguage,MSymbolname)
       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.
       RETURNVALUEIfnoinputmethodcommandsarefound,thisfunctionreturnsNULL.
       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.

   intminput_assign_command_keys(MSymbollanguage,MSymbolname,MSymbolcommand,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.
       RETURNVALUEIftheoperationwassuccessful,0isreturned.Otherwise-1isreturned,andmerror_codeissettoMERROR_IM.MPlist*minput_parse_im_names(MText*mt)
       Parse input method names. The minput_parse_im_names() function parses M-text mt and  returns  a  list  of
       input  method  names.  Input  method  names  in  mt must be separated by comma (','). Input methods whose
       language is Mt can be specified by its name only (i.e. just 'latn-post' instead of 't-latn-post').
       RETURNVALUETheminput_parse_im_names()returnsaplistofwhichelementsareplistofLANGUAGEandNAMEofinputmethodsasbelow:((LANGUAGE1NAME1)(LANGUAGE2NAME2)...)BothLANGUAGEnandNAMEnaresymbols.LANGUAGEnisMtifthecorrespondinginputmethodisnotlimitedtoaspecificlanguage.Ifaspecifiedinputmethoddoesn'texist,thecorrespondingelementintheaboveplistisasub-partofmtforthatnon-existinginputmethodname.Forinstance,if'symbol,unknown,unicode'isspecifiedasmtand'unknown'doesn'texist,thereturnvalueis:((tsymbol)'unknown'(tunicode))intminput_callback(MInputContext*ic,MSymbolcommand)
       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.
       RETURNVALUEIfthereexistsaspecifiedcallbackfunction,0isreturned.Otherwise-1isreturned.Bysideeffects,ic->plistmaybemodified.

       m17nInputMethod_-_Input_Method_(ba -  - API for Input method.

DataStructures
       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'.
       MInputDriverminput_default_driver
           The default driver for internal input methods.
       MInputDriver * minput_driver
           The driver for internal input methods.
       MSymbol Minput_driverVariables:Predefinedsymbolsforcallbackcommands.<br>
        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_textVariables:Predefinedsymbolsforspecialinputevents.
        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_moveVariables:Predefinedsymbolsusedininputmethodinformation.<br>
       MSymbol Minherited
       MSymbol Mcustomized
       MSymbol MconfiguredFunctionsMInputMethod * 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)
       int minput_config_command (MSymbol language, MSymbol name, MSymbol command, MPlist *keyseqlist)
       MPlist * minput_get_variable (MSymbol language, MSymbol name, MSymbol variable)
       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.
       MPlist * minput_list (MSymbol language)

   ObsoletefunctionsMPlist * minput_get_variables (MSymbol language, MSymbol name)
       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).
       MPlist * minput_parse_im_names (MText *mt)
           Parse input method names.
       int minput_callback (MInputContext *ic, MSymbol command)
           Call a callback function.

typedefvoid(*MInputCallbackFunc)(MInputContext*ic,MSymbolcommand)
       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.

MSymbolMinput_method
       Symbol whose name is 'input-method'.
   MSymbolMinput_preedit_startMSymbolMinput_preedit_doneMSymbolMinput_preedit_drawMSymbolMinput_status_startMSymbolMinput_status_doneMSymbolMinput_status_drawMSymbolMinput_candidates_startMSymbolMinput_candidates_doneMSymbolMinput_candidates_drawMSymbolMinput_set_spotMSymbolMinput_toggleMSymbolMinput_resetMSymbolMinput_get_surrounding_textMSymbolMinput_delete_surrounding_textMSymbolMinput_focus_outMSymbolMinput_focus_inMSymbolMinput_focus_moveMSymbolMinherited
       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().

   MSymbolMcustomizedMSymbolMconfiguredMInputDriverminput_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.

   MSymbolMinput_driver
       The variable Minput_driver is a symbol for a foreign input method.  See  foreigninputmethod  for  the
       detail.