m17nInputMethod(3m17n)

📦
version 1.8.4 · 2 versions
, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 m17nInputMethod 💖

okay so this is the m17nInputMethod(3m17n) page from The m17n Library, and it's literally the blueprint for input methods. bestie, we're gonna go through it together, no skipped details, fr fr. 💅

✨ NAME ✨

The NAME line says: m17nInputMethod_-_Input_Method_(ba - - API for Input method. — yeah, that's the whole vibe.

🌸 SYNOPSIS 🌸

🎀 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. " (yes, there's a lil stray quote at the end, iconic.)

🍓 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 — (no description in the original, it's just there being mysterious)

💜 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) — (no description in the original)
  • int minput_config_command (MSymbol language, MSymbol name, MSymbol command, MPlist *keyseqlist) — (no description in the original)
  • MPlist * minput_get_variable (MSymbol language, MSymbol name, MSymbol variable) — (no description in the original)
  • 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) — (no description in the original)

💀 Obsolete functions 💀

  • MPlist * minput_get_variables (MSymbol language, MSymbol name) — (no description in the original)
  • 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.

👑 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

Structure of input method driver. It's giving "the blueprint of how an IM actually drives", bestie.

✨ FIELD DOCUMENTATION ✨

  • int(* MInputDriver::open_im) (MInputMethod *im) — Opens an input method. This one opens the input method im. It gets called from minput_open_im(), and it runs after every member of im except <info> has been set. If opening im works, it returns 0. If it doesn't, it returns -1. The function is allowed to set up im->info to stash all kinds of info that the other driver functions will come back and read. 👑
  • void(* MInputDriver::close_im) (MInputMethod *im) — Closes an input method. This closes im. It gets called from minput_close_im(). It frees all the memory allocated for im->info (if any) after it finishes every task involved in closing the input method. But heads up — the other members of im must not be touched. 🙅♀️
  • int(* MInputDriver::create_ic) (MInputContext *ic) — Creates an input context. This makes the input context ic. It's called from minput_create_ic() after every member of ic except <info> has been set. If creating ic succeeds, it returns 0. If not, -1. The function can set up ic->info to keep various info that the other driver functions refer to. ✨
  • void(* MInputDriver::destroy_ic) (MInputContext *ic) — Destroys an input context. This one gets called from minput_destroy_ic() and destroys the input context ic. It frees all the memory allocated for ic->info (if any) after it finishes every task of destroying the input method. But again — the other members of ic should not be touched. 💀
  • int(* MInputDriver::filter) (MInputContext *ic, MSymbol key, void *arg) — Filters an input key. Called from minput_filter(), and it filters an input key. key and arg are literally the same ones given to minput_filter(). The job here is to handle key and update the internal state of ic. If key gets 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's what's needed for the member <callback>. 🫶 The meaning of arg depends on the input method driver. Peep the documentation of minput_default_driver and minput_gui_driver for the tea, for instance. 🍓
  • int(* MInputDriver::lookup) (MInputContext *ic, MSymbol key, void *arg, MText *mt) — Looks up a produced text in an input context. Called from minput_lookup(), it looks up a produced text in the input context ic. This function concatenates a text produced by the input key key (if any) onto 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 docs for minput_default_driver and minput_gui_driver, for instance. 💜
  • MPlist* MInputDriver::callback_list — List of callback functions. List of callback functions. (Yes bestie, it really says it twice.) 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 have a property of key Minput_driver, and the value must be a pointer to a proper input method driver. periodt. 💅
  • 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() sets up.

👑 MInputContext

Structure of input context. This is the main character of the whole operation, ngl.

✨ FIELD DOCUMENTATION ✨

  • MInputMethod* MInputContext::im — Backward pointer to the input method. It gets set up by the function minput_create_ic().
  • MText* MInputContext::produced — M-text produced by the input method. Set up by the function minput_filter().
  • void* MInputContext::arg — Argument given to the function minput_create_ic().
  • int MInputContext::active — Flag telling whether the input context is currently active or inactive. It's set to 1 (active) when the input context is created. It gets toggled by the function minput_toggle(). ✨
  • int MInputContext::x — X and Y coordinate of the spot.
  • int MInputContext::y — (the other half of that X and Y coordinate of the spot 🫶)
  • int MInputContext::ascent — Ascent and descent pixels of the line of the spot.
  • int MInputContext::descent — (the descent half of those pixels 💜)
  • int MInputContext::fontsize — Font size for preedit text, measured 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're set by the function <im>->driver.filter(). Pointer to extra information that <im>->driver.create_ic() sets up. It's 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's a plist (i.e. the key is Mplist), each element is an M-text, and the candidates in that group are those M-texts. 🍓
  • int MInputContext::candidate_index — Index number of the currently selected candidate across all the candidates. The index of the first candidate is 0. So like, if the number is 8, and the first candidate group contains 7 candidates, then the currently selected candidate is the second element of the second candidate group. math bestie 🧮✨
  • int MInputContext::candidate_from — Start and the end positions of the preedit text where <candidate_list> corresponds to.
  • int MInputContext::candidate_to — (the end position half of that range 💅)
  • 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 requires showing candidates, and sets the value to 0 otherwise. 👀
  • int MInputContext::candidates_changed — The function <im>->driver.filter() sets the value to the 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 results 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 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, and command is a name of the callback for which the function is called. ✨

🌈 Enumeration Type Documentation 🌈

🎀 enum MInputCandidatesChanged

Bit-masks to specify how candidates of input method is changed. Slay, a whole enum of vibes.

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 they're 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. So it's the programmer's responsibility to set it to a plist of proper callback functions. Otherwise, no feedback information (like preedit text, bestie 😭) 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's 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. (not me writing fanfic, the robot did it 💀)

MPlist* minput_get_variables (MSymbol language, MSymbol name)</p>

@brief Get a list of variables of an input method (obsolete).

okay bestie, heads up first: this function is obsolete. like, retired. use minput_get_variable() instead, fr fr 💅

so the minput_get_variables() function returns a plist (#MPlist) of variables that control the behavior of the input method you point at with language and name. that plist is a well-formed one (@ref m17nPlist), and it's shaped like this:

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

breaking it down:

  • VARNAME is a symbol that represents the variable name.
  • DOC-MTEXT is an M-text describing the variable.
  • DEFAULT-VALUE is the default value of the variable. it's a symbol, integer, or M-text.
  • VALUEs (if there even are any) spell out the possible values of the variable. and if DEFAULT-VALUE is an integer, VALUE may be a plist (FROM TO), where FROM and TO specify a range of possible values.

now for a lil example 🌸 — say an input method has these 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:

(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. and because the plist lives inside the library, the caller must not modify it or free it, okay? hands off 🙈 if the input method doesn't use any variable at all, NULL is returned.

int minput_set_variable (MSymbol language, MSymbol name, MSymbol variable, void * value)</p>

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. (so like, go open a fresh one, bestie ✨)

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)</p>

Get information about input method commands. the minput_get_commands() function returns info about input method commands of the input method specified by language and name. an input method command is a pseudo key event that one or more actual input key sequences are assigned to.

there are two kinds of commands, global and local. global commands get used by multiple input methods for the same purpose, and they have global key assignments. local commands are used only by one specific input method, and they 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 doesn't 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.

and again — the returned plist is kept in the library, so the caller must not modify nor free it. don't touch, just vibe 💜

int minput_assign_command_keys (MSymbol language, MSymbol name, MSymbol command, MPlist * keyseq)</p>

Assign a key sequence to an input method command (obsolete). this function is obsolete, bestie 😭 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.

MPlist* minput_parse_im_names (MText * mt)</p>

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'). so convenient, honestly ✨

RETURN VALUE

the minput_parse_im_names() returns a plist of which elements are plist of LANGUAGE and NAME of input methods as below:

((LANGUAGE1 NAME1) (LANGUAGE2 NAME2) ...)

both LANGUAGEn and NAMEn are symbols. LANGUAGEn is Mt if the corresponding input method is not limited to a specific language. if a specified input method doesn't exist, the corresponding element in the above plist is a sub-part of mt for that non-existing input method name. for instance, if 'symbol,unknown,unicode' is specified as mt and 'unknown' doesn't exist, the return value is:

((t symbol) 'unknown' (t unicode))

int minput_callback (MInputContext * ic, MSymbol command)</p>

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. (yes, it can just ✨change✨ on you, so watch out)

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

and that's a wrap on the whole page, bestie!! 🎀 this was m17nInputMethod(3m17n), straight out of the source at Version 1.8.4, dated Mon Sep 25 2023 — iconic, no cap. go forth and configure those input methods, you absolute main character 💅🦋👑

📦 where this page comes from