Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Input Method (basic)(3m17n)	 Version 1.5.5	   Input Method	(basic)(3m17n)

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.

   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.

   Typedefs
       typedef struct MInputMethod MInputMethod
	   See struct MInputMethod.
       typedef struct MInputContext MInputContext
	   See struct MInputContext.
       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

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.

       o 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.
       o 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:
       o open an input method
       o create	an input context for the input method
       o filter	an input key
       o look up a produced text in the	input context
Data Structure Documentation
   MInputDriver
       Structure of input method driver.

       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
       Structure of input method.

       FIELD DOCUMENTATION:
       MSymbol MInputMethod::language
       Which language this input method	is for.	The value is Mnil if the input
       method is foreign.
       MSymbol MInputMethod::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.
       MInputDriver MInputMethod::driver
       Input method driver of the input	method.
       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.

       FIELD DOCUMENTATION:
       MInputMethod* MInputContext::im
       Backward	pointer	to the input method. It	is set up be the function
       minput_create_ic().
       MText* MInputContext::produced
       M-text produced by the input method. It is set up by the	function
       minput_lookup() .
       void* MInputContext::arg
       Argument	given to the function minput_create_im().
       int MInputContext::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().
       int MInputContext::x
       X and Y coordinate of the spot.
       int MInputContext::y
       int MInputContext::ascent
       Ascent and descent pixels of the	line of	the spot.
       int MInputContext::descent
       int MInputContext::fontsize
       Font size for preedit text in 1/10 point.
       MText* MInputContext::mt
       M-text at the spot, or NULL.
       int MInputContext::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::status
       M-text describing the current status of the input context.
       int MInputContext::status_changed
       The function <im>->driver.filter() sets the value to 1 when it changes
       <status>.
       MText* MInputContext::preedit
       M-text containing the current preedit text. The function
       <im>->driver.filter() sets the value.
       int MInputContext::preedit_changed
       The function <im>->driver.filter() sets the value to 1 when it changes
       <preedit>.
       int MInputContext::cursor_pos
       Cursor position of <preedit>.
       int MInputContext::cursor_pos_changed
       The function <im>->driver.filter() sets the value to 1 when it changes
       <cursor_pos>.
       MPlist* MInputContext::candidate_list
       Plist of	the current candidate groups. Each element is an M-text	or a
       plist. If an element is an M-text (i.e. the key is Mtext), candidates
       in that group are characters in the M-text. If it is a plist (i.e. the
       key is Mplist), each element is an M-text, and candidates in that group
       are those M-texts.
       int MInputContext::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.
       int MInputContext::candidate_from
       Start and the end positions of the preedit text where <candidate_list>
       corresponds to.
       int MInputContext::candidate_to
       int MInputContext::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.
       int MInputContext::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::plist
       Plist that can be freely	used by	<im>->driver functions.	The driver of
       internal	input method uses it to	exchange extra arguments and result
       for callback functions. The function <im>->driver.create_ic() sets this
       to an empty plist, and the function <im>->driver.destroy_ic() frees it
       by using	m17n_object_unref().

Typedef	Documentation
   typedef struct MInputMethod MInputMethod
       See struct MInputMethod.
   typedef struct MInputContext	MInputContext
       See struct MInputContext.
   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.
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:
       o name:intvar, description:'value is an integer', initial value:0,
	 value-range:0..3,10,20
       o name:symvar, description:'value is a symbol', initial value:nil,
	 value-range:a,	b, c, nil
       o 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-2009 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>.

				  15 Oct 2009	   Input Method	(basic)(3m17n)

NAME | Detailed Description | Data Structure Documentation | Typedef Documentation | Enumeration Type Documentation | Variable Documentation | Function Documentation | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=m17nInputMethod&sektion=3m17n&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help