[SCIM] Re: [m17n-lib:00106] Re: SCIM help for M17N input methods (was: Custom Keyboard Layout Editor/Interpreter for SCIM)

[Zhe Su]

Hi,
 Looks good to me.  So please go ahead to implement these APIs. I'll
make use of them in scim-m17n as soon as they are available.

Regards
James Su


On Thu, 13 Jan 2005 17:30:54 +0900 (JST), Kenichi Handa <handa@m17n.org> wrote:
> Zhe Su <james.su@gmail.com> writes:
> >   Such approach is good, but too complicated to be implemented in
> > current scim-m17n and scim. So for short term solution, is it possible
> > to just give a plain text help including the URL to the real help
> > webpage.
> 
> Sorry for the late response on this matter.
> 
> I'm going to implement these new API's (the detail is
> attached at the tail).  I'd like to hear your opinions.
> 
> (1) For getting a description text of an input method
> 
> See minput_get_description () below.
> 
> (2) For customizing input keys
> 
> I'm going to allow to specify a pseudo input key (instead of
> the current realy key (key sequence)) in *.mim file.  I'll
> name such a key as "input method command", and make it
> customizable by using the functions minput_get_command_keys
> () and minput_set_command_keys ().
> 
> For instance, currently several m17n input methods contains
> this kind of code:
> 
>  (change-candidate
>   ((Left) (select @-))
>   ((Right) (select @+))
>   ((Up) (select @[))
>   ((Down) (select @])))
> 
> I'd like to change it to something like this:
> 
>  (change-candidate
>   (prev-candidate (select @-))
>   (next-candidate (select @+))
>   (prev-candidate-group (select @[))
>   (next-candidate-group (select @])))
> 
> Here, prev-candidate, next-candidate, ... are the input
> method commands.  I'll make m17n-db to provide the default
> definition of them as this:
> 
> (prev-candidate
>  ((Left) (C-B))  <- list of assigned keys
>  "Previous candidate" <- brief description
>  "Select the previous candidate" <- defailed description
>  )
> 
> Then, by using minput_get_command_keys () to retrieve that
> information and minput_set_command_keys to update the list
> of assigned keys, we can make a GUI for customizing command
> keys.
> 
> Each input method can have its own command definitions that
> are used only in that input method.  For instance, in
> ja-anthy.mim:
> 
>  (convert-to-katakana
>   ("K")
>   "Convert to katakana"
>   "Convert the preedit text to Katakana")
>  (convert-to-hiragana
>   ("H")
>   "Convert to hiragana"
>   "Convert the preedit text to Hiragana"))
> 
> It may be good if this kind of information can be shared
> among the other input methods (not those of m17n-lib).
> 
> (3) For customizing the behaviour of an input method
> 
> It is good to reflect a users preference on the behaviour of
> input method.  For instance, in CJK input methods, one may
> prefer FULLWIDTH COMMA (U+FF0C) and FULLWIDTH FULLSTOP
> (U+FF0E) to IDEOGRAPHIC COMMA (U+3001) and IDEOGRAPHIC
> FULLSTOP (U+3002).
> 
> For such a case, I'm going to allow to have this kind of
> specification in *.mim file.
> 
>  (punctuation-mode
>   (0 "IDEOGRAPHIC"
>      "Use IDEOGRAPHIC COMMA and FULLSTOP (U+3001, U+3002)")
>   (1 "FULLWIDTH"
>      "Use FULLWIDTH COMMA and FULLSTOP (U+FF0C, U+FF0E)")
>   (2 "ASCII"
>      "Use ASCII COMMA and FULLSTOP"))
> 
> Then minput_get_variables () and minput_set_variable () can
> be used to customize it.
> 
> (4) For loading and saving the customization.
> 
> It's upto users of m17n-lib (e.g. SCIM and UIM) how to save
> and load the above customization, but
> minput_load_customization and minput_save_customization may
> be convenient.
> 
> ---
> Ken'ichi HANDA
> handa@m17n.org
> 
> 
> /***en
>     @brief Key of a text property for detailed description.
> 
>     The symbol #M_details is a managing key usually used for a text
>     property whose value is an M-text that contains detailed
>     description.  */
> MSymbol M_details;
> 
> /***en
>     @brief Get description text of an input method
> 
>     The minput_get_description () function returns an M-text briefly
>     describing the input method specified by $LANG and $NAME.  It may
>     have a text property #M_details whose value is an M-text
>     describing the input method in more detail.
> 
>     @return
>     If the specified input method has a description text, a pointer to
>     #MText is returned.  A caller have to free it by m17n_object_unref ().
>     If the input method does not have a description text, NULL is
>     returned.  */
> 
> MText *
> minput_get_description (MSymbol lang, MSymbol name)
> {
>   /* ... */
> }
> 
> /***en
>     @brief Get information about input method commands
> 
>     The minput_get_command_keys () function returns information about
>     input method commands of the input method specified by $LANG and
>     $NAME.  An input method command is a pseudo key event to which
>     actual input keys or input key sequences are assigned.
> 
>     If both $LANG and $NAME are #Mnil, this function returns
>     information about global input method commands used by all input
>     methods consistently; i.e. the same command is used for the same
>     purpose in all input methods (e.g. for selecting a candidate).
> 
>     The return value is a plist (#MPlist) whose keys are symbols
>     representing a command, and values are COMMAND-PLIST, a plist
>     defining that command.  Each definition contains a description
>     text and one or more input key sequences assigned to the command
>     by elements of the following format.
> 
>     If a key is #Mplist, the value is a plist whose keys are #Msymbol
>     and values are symbols representing input keys.  This sequence of
>     input keys are currently assigned to the command.  COMMAND-PLIST
>     may have multiple elements of this format.  In that case, all key
>     sequences are assigned to the command.
> 
>     If a key is #Mtext, the value is an M-text describing the meaning
>     of the command briefly.  This M-text may have a text property
>     #M_details whose value is an M-text describing the command in more
>     detail.
> 
>     @return
>     If there are commands (per input-method or globally), a pointer to
>     #MPlist is returned.  As the plist is kept in the library, a
>     caller must not modify or free it.  If there are no command, NULL
>     is returned.  */
> 
> MPlist *
> minput_get_command_keys (MSymbol lang, MSymbol name)
> {
>   /* ... */
> }
> 
> /***en
>     @brief Assign input keys to an input method command
> 
>     The minput_set_command_keys () function assigns input keys $KEYS
>     to an input method command $COMMAND for the input method specified
>     by $LANG and $NAME.  If both $LANG and $NAME are #Mnil, the input
>     keys are assigned to the global command.
> 
>     An element of $KEYS has $Mplist as key and KEYSEQ-PLIST as value.
>     KEYSEQ-PLIST is a plist representing a key sequence to be assigned
>     to the command.  An element of KEYSEQ-PLIST has $Msymbol as key
>     and a symbol of input key as value.
> 
>     This assignment is reflected in a newly opened input method.
> 
>     @return
>     If the operation was successful, 0 is returned.  Otherwise -1 is
>     returned, and #merror_code is set to #MERROR_IM.  */
> 
> int
> minput_set_command_keys (MSymbol lang, MSymbol name,
>                          MSymbol command, MPlist *keys)
> {
>   /* ... */
> }
> 
> /***en
>     @brief Get a list of variables of an input method
> 
>     The minput_get_variables () function returns a plist (#MPlist) of
>     variables used to control the behaviour of the input method
>     specified by $LANG and $NAME.  Keys of the plist are symbols
>     representing the variables and values are plists carrying the
>     information about the corresponding variable in this format.
> 
>     If a key of the plist is #Mtext, the value is an M-text describing
>     the variable briefly.  This M-text may have a text property
>     #M_details whose value is an M-text describing the variable in
>     more detail.
> 
>     If a key of the plist is #Mplist, the value is VALUE-PLIST, a
>     plist of possible values of the variable.
> 
>     Each element of VALUE-PLIST has key #Minteger or #Mtext by turns.
> 
>     If the key is #Minteger, the value is one of possible integer
>     values of the variable.
> 
>     If the key is #Mtext, the value is an M-text describing the
>     meaning of the value specified in the previous element.  This
>     M-text may have a text property #M_details whose value is an
>     M-text describing the value in more detail.
> 
>     In short, the returned plist has this form ('X:Y' means X is a key
>     and Y is a value, and '(...)' means a plist):
> @verbatim
>     (VAR1-NAME:(mtext:VAR1-DESCRIPTION
>                 plist:(integer:VAL1
>                        mtext:VAL1-DESCRIPTION
>                        integer:VAL2
>                        mtext:VAL2-DESCRIPTION
>                        ...))
>      VAR2-NAME:...
>      ...)
> @endverbatim
> 
>     @return
>     If the input method uses some variable, a pointer to #MPlist is
>     returned.  As the plist is kept in the library, a caller must not
>     modify nor free it.  If the input method does not use any
>     variable, NULL is returned.  */
> 
> MPlist *
> minput_get_variables (MSymbol lang, MSymbol name)
> {
>   /* ... */
> }
> 
> /***en
>     @brief 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 $LANG and $NAME.
> 
>     By default, the initial value is 0.
> 
>     This setting is reflected to a newly opened input method.
> 
>     @return
>     If the operation was successful, 0 is returned.  Otherwise -1 is
>     returned, and #merror_code is set to #MERROR_IM.  */
> 
> int
> minput_set_variable (MSymbol lang, MSymbol name, MSymbol variable, int value)
> {
>   /* ... */
> }
> 
> /***en
>     @brief Load customization information of input methods
> 
>     The minput_load_customization () function loads customization
>     information of input methods from M-text $MT.
> 
>     @return
>     If the operation was successful, 0 is returned.  Otherwise -1 is
>     returned, and #merror_code is set to #MERROR_IM.  */
> 
> int
> minput_load_customization (MText *mt)
> {
>   /* ... */
> }
> 
> /***en
>     @brief Save customization information of input methods
> 
>     The minput_save_customization () function return an M-text that
>     contains customization information of input methods.  The M-text
>     is valid as an argument to minput_load_customization ().
> 
>     @return
>     If there exists customization information, a pointer to #MText is
>     returned.  Otherwise, NULL is returned.
> */
> 
> MText *
> minput_save_customization (void)
> {
>   /* ... */
> }
>