Provided by: tklib_0.8~20230222-1_all bug

NAME

       khim - Provides key bindings for entering international characters on a keyboard that does
       not support them

SYNOPSIS

       package require Tcl

       package require khim  ?1.0?

       ::khim::getOptions path

       ::khim::getConfig

       ::khim::setConfig version enabled compose map

       ::khim::showHelp path

_________________________________________________________________________________________________

DESCRIPTION

       This package provides a set of key bindings to allow a user to enter arbitrary  characters
       on a keyboard that does not support them.  It works by designating some seldom-used key of
       the keyboard as a "Compose" key (this key is distinct from any  key  so  labeled,  and  is
       often  "Pause,"  "F12"  or  "L2"),  and  having  the  "Compose" key, followed by a two-key
       sequence, have the effect of inserting some character  in  a  widget.   In  addition,  the
       "Compose"  key,  when  struck twice in succession, brings up a dialog containing a Unicode
       character map, allowing arbitrary characters to be inserted.

       The vast bulk of the package's functionality is implemented in a single bindtag, KHIM.  An
       application  can  request that any text or entry widget use the package to allow for entry
       of arbitrary characters by placing this binding tag ahead of the Text or Entry binding tag
       for the widget:

              text .t -width 80 -height 24
              bindtags .t {.t KHIM Text . all}

       Note  that  the KHIM tag must precede the Text or Entry class binding, or the package will
       not function correctly.

PROCEDURES

       In addition to commands supporting the  KHIM  binding  tag,  the  following  commands  are
       exported from the package:

       ::khim::getOptions path
              Posts  a  top-level  modal dialog with the path name path that prompts the user for
              KHIM options.  The user is  allowed  to  reconfigure  the  key  sequences  for  the
              "Compose"  key,  change  the  choice  of key to use for the "Compose" function, and
              enable/disable the KHIM key bindings entirely.

       ::khim::getConfig
              Returns a  Tcl  script  that  restores  the  current  configuration  of  KHIM:  the
              enabled/disabled state, the choice of "Compose" key, and the key sequences that may
              be composed.  This script is designed to be saved to a configuration file  for  use
              in a subsequent invocation of the same application:

              # Save KHIM configuration
              set f [open ~/.khimrc w]
              puts $f [::khim::getConfig]
              close $f

              # Restore KHIM configuration
              source ~/.khimrc

       ::khim::setConfig version enabled compose map
              Restores  an earlier saved configuration.  Few, if any, applications will call this
              command in any other way than to evaluate it as returned from ::khim::getConfig.

       ::khim::showHelp path
              Displays a top-level dialog giving user-level help for KHIM; the dialog  will  have
              the path name path.

LOCALISATION

       Programmers  who wish to make KHIM available in a non-English-speaking locale may do so by
       providing a .msg file with the appropriate  localised  text.   The  catalog  requires  the
       following messages:

       Apply  Text that will appear on the "Apply" button in the dialog that sets KHIM options.

       Cancel Text that will appear on the "Cancel" button in several dialogs.

       Change Text that will appear on the "Change" button, which alters the binding of a pair of
              composed characters (creating or replacing as appropriate).

       Character
              Text that will appear on the label of the entry widget  that  accepts  a  character
              resulting from a composed sequence.

       {Compose Key}
              Window title for a dialog that prompts the user to strike the key that will be used
              for the "Compose" key.

       {Compose key:}
              Label that identifies a component showing the "Compose"  key  choice  in  the  KHIM
              options dialog.

       {Composed sequence must be two characters long}
              Error message that is displayed if the user attempts to define a "Compose" sequence
              that is shorter or longer than two characters.

       Delete Text for a button that deletes a "Compose" sequence.

       Help...
              Text for a button that displays the KHIM user help dialog.

       HELPTEXT
              Complete text for the user-level help for KHIM.  Refer to "en.msg" for the English-
              language version of the help.

       {Input key sequence}
              Text  for  a  label  of  the entry widget that prompts the user for a two-character
              sequence to use with the "Compose" key.

       {Insert Character}
              Window title of the dialog box that displays a Unicode character  map  and  prompts
              the user to select a character to insert.

       {Key sequences}
              Text  for  a label at the head of a listbox showing the composed sequences that are
              currently bound.

       {KHIM Controls}
              Window title for the dialog box that prompts for KHIM settings.

       {KHIM Help}
              Window title for the window that display help text for KHIM.

       OK     Label for the OK button on several dialogs.

       Select code page:
              Label for a spinbox that prompts the user for a Unicode code page number.

       SELECT COMPOSE KEY
              A message, which should be composed in short lines, prompting the user to press the
              key that will become the "Compose" key in KHIM.

       Unicode...
              Text for a button that brings up the character map to select the character to which
              a composed sequence binds.

       {Use KHIM}
              Text for a checkbutton that asks whether the user wishes  to  use  KHIM  to  manage
              composed key sequences.

ACKNOWLEDGMENTS

       KHIM  was  originally  inspired  by  the  key  bindings that Brent Welch developed for the
       'sedit' editor used in the 'exmh' mail user agent.  The code for KHIM is entirely separate
       from that for 'sedit'.

BUGS, IDEAS, FEEDBACK

       This  document,  and  the  package  it  describes, will undoubtedly contain bugs and other
       problems.   Please  report  such  in   the   category   khim   of   the   Tklib   Trackers
       [http://core.tcl.tk/tklib/reportlist].   Please also report any ideas for enhancements you
       may have for either package and/or documentation.

KEYWORDS

       character, i18n, input, international, method