<!doctype linuxdoc system>

<!-- kde handbook
 -->

<article>

<!-- Title information -->

<title>International Keyboard Handbook
<author>Alexander Budnik, <tt>budnik@linserv.jinr.ru</tt> and
Dimitrios P. Bouras, <tt>dbouras@hol.gr</tt>  .  Document revision
by Duncan <tt>duncan@kde.org</tt> 
<date>v1.0b4, March 24 1999, revisions August 23, 1999,
<abstract>This Handbook describes International Keyboard Version 1.0b4

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<sect>Introduction<p>

  <bf>KDE International Keyboard</bf> (<tt>kikbd</tt>)
   is designed to help type national symbols different from the
  default Latin symbols under X11. 

  <tt>kikbd</tt> implements keyboard layout support for national character-sets
  other than the default Latin-1. Instead of relying on the <it>classic</it>
  method which uses X keyboard maps and modifier keys or, since X11R6.1
  came out, XKB map files and rules, <tt>kikbd</tt> can remember more than one
  keyboard map, and can switch to any desired one in a dynamic fashion.

  <tt>kikbd</tt> uses the <tt>xmodmap</tt> method to set up 
  national keyboard maps for X11
  applications, but can handle dynamic switching between keyboard maps
  selected from the list.
  This means it can support more than one language at a time.

  In addition to this, <tt>kikbd</tt> can also maintain different keyboard maps
  for different windows or applications (using <it>Window</it> or <it>Class</it>
  input styles respectively).

</sect>

<sect>Installation<p>

  Installation from sources follows the  usual procedure :-)
  <verb>
     % ./configure
     % make
     % make install
  </verb>
  You need at least KDE 1.0 to successfully compile <tt>kikbd</tt>. 
  <comment>
  Starting with KDE version 1.1, <tt>kikbd</tt> is included in the
  <tt>kdebase</tt> package.
  </comment>

</sect>

<sect>National Keyboard<p>

  For each language or national keyboard, <tt>kikbd</tt> supports a 
  <it>keyboard map</it> 
  which can have up to four symbols per physical keyboard key. For 
  example in the Russian keyboard you have four symbols for key 'Q': 
  lowercase i, uppercase I, lowercase  q, and uppercase Q. 
  The first two symbols are 
  the national character-set  keyboard-map symbols and the last two
  symbols are the <it>alternate symbols</it>.
 
  For typing <it>alternate symbols</it> you 
  have to set up a choice of a
  special <bf>Alternate Switch</bf> key in the 
  <tt>kikbd</tt> configuration; for details,  see the
  <ref id="config" name="Personal Configuration section">. 
  Normally the first symbol is obtained by typing without any modifier
  keys pressed, the second symbol when you type with the <bf>Shift</bf>
   held down,
  the third symbol when you type with the <bf>Alternate Switch</bf> 
  held key down,
  and the fourth symbol when you type with the <bf>Alternate Switch</bf>
  +  <bf>Shift</bf> keys <it>both</it> held down.<p>

  At the time this was  written, there were more than twenty
  national keyboard definition files already in the <tt>kikbd</tt> distribution.

  If a keyboard for your language is missing see section 
  <ref id="create" name="Creating a new National Keyboard">.


  The  International Keyboard
  ``Personal configuration'', using the  <tt>kcmikbd</tt>
  Control Center module, 
  includes all your runtime settings for <tt>kikbd</tt>.
  You should use the KDE Control Center module
  program <tt>kcmikbd</tt>  
  for creating/modifing your personal
  configuration. When you start <tt>kikbd</tt> or <tt>kcmikbd</tt>
  for the first time it will
  copy the default system configuration to your personal configuration.

To run <tt>kcmikbd</tt>, go to the <bf>Settings</bf> menu or the <bf>The KDE Control Center</bf>
and choose ``<bf>Input Devices</bf>'' and then
``<bf>International Keyboard</bf>''.  

To run <tt>kikbd</tt>, go to the <bf>System</bf> menu 
and choose 
``<bf>International Keyboard Layout</bf>''.  



<sect> Configuring the KDE International Keyboard.<label id="config"<p>

There are three configuration dialogs for the
KDE <it>International Keyboard</it>.

<itemize>

<item> The  <ref id="general" name="General"> settings dialog,
for selecting the keyboard map, and hot keys. This also
accesses the  <ref id="advanced" name="Advanced Options"> dialog.

<item> The <ref id="style" name="Style"> dialog for
configuring the fonts and colors used by the <it>International
Keyboard</it> keyboard-indicator button.

<item> The <ref id="startup" name="Startup"> dialog for
configuring how the <it>International Keyboard</it> is started, 
and the placement of the keyboard-indicator  button.

</itemize>

<sect>International Keyboard - General settings<label id="general"><p>



The  <it>KDE International Keyboard</it>
program (<tt>kikbd</tt>) allows you to select
different keyboard maps for various national languages so you can
easily switch between different  national keyboard layouts.
The program is started
by clicking on the <bf>International Keyboard Layout</bf> item
in the <bf>System</bf> menu; it may also be configured to start
automatically every time you start  the KDE Desktop.
You can switch between different keyboard layouts
by using  a 
specially-defined <bf>Switch</bf>
``hotkey'' combination, or by 
clicking on the <bf>keyboard-indicator
button</bf> that is present whenever the <it>International Keyboard</it> 
program  is running.   


  <p><img SRC=general.gif>

The <bf>General Settings</bf>  dialog configures the keyboard
maps and ``hotkeys''.


<bf>Keyboard maps</bf>:

Your personal list of national keyboard maps is shown in the box.   The
first entry is the  <it>default</it> keyboard map,
used by <it>International Keyboard</it> when it starts.  When you start
the  <it>International Keyboard</it> program (or its Control Center
configuration module) for the first time, the current keyboard map
is copied to your personal list of keyboard maps  as the default entry.
(In the example screenshot above, the default keyboard is
<tt>En</tt> - US English Language.)



Use the buttons at the right to control your keyboard map list.
<itemize>
<item>Click on the <bf>Add</bf> button to add entries to
the list of keyboard maps.   
This opens the
<bf>Add Keyboard</bf> dialog which has a pull-down list of available
keyboard maps, and gives information about the keyboard you select
from it.  Click on its <bf>OK</bf> button to add the chosen keyboard map
to your personal list, or on <bf>Cancel</bf> to close the dialog without
changing your list.

<item>
Click on the <bf>Delete</bf> button to remove the selected  
(highlighted) keyboard map from your personal list.

<item> Use the <bf>Up</bf> and <bf>Down</bf> buttons to select 
a  keyboard map by moving up or down in your personal list.  
The selected keyboard, which is
highlighted, is the ``<it>hot</it>'' keyboard.

<item>
Click on the <bf>Info</bf> button to view the
<bf>Keyboard Map Information</bf>  about the  selected
keyboard.

</itemize>
<p>
    If you use more then two keyboard maps, it is very helpful to activate
    the ``<bf>Use hotlist</bf>'' option. In this case you can switch between
    the ``<it>hot</it>'' (highlighted) keyboard and the <it>default</it> 
    (first) keyboard by 
    using the <bf>Switch</bf>
    key(s).  
    You can  change the choice of 
    ``<it>hot</it>'' keyboard in the <it>International Keyboard</it>  
    pop-up menu
    that appears when you right-click on the 
    keyboard-indicator  button.


<bf>Switch and Alt Switch</bf>:
<p>
This section allows you to choose the ``hotkey'' combinations  used
by  <it>International Keyboard</it>  for
the <bf>Switch</bf> and <bf>Alternate Switch</bf> keys.

The box on the left shows the key combination chosen for
the <bf>Switch</bf> key .
<itemize>
<item> Pressing the <bf>Switch</bf> key combination switches the keyboard
map to the the next one in your personal list of keyboard maps 
(or between the <it>default</it> and the highlighted (``<it>hot</it>'') 
map, if
the ``<bf>use hotlist</bf>'' option is active).   
</itemize>

The box on the right shows the key chosen as the <bf>Alternate Switch</bf>
key. This acts as a second shift-type key for accessing any
<it>alternate characters</it> defined in the keyboard map.
 
<itemize>
<item> The ``lower-case''  alternate characters
in the keyboard map
for the current national keyboard 
are obtained if the key is typed with the <bf> Alternate Switch</bf> key
held down, and the ``upper-case'' alternate characters
are obtained if the key is typed with both the <bf>Alternate Switch</bf> and
the <bf> Shift</bf> held down.
</itemize>
Both boxes have a pull-down menu allowing different choices for these
special keys to be selected.

In the  example screenshot above, you can switch between
keyboards by pressing <bf>Right Ctrl</bf>
and <bf>Right Shift</bf>  keys 
at the same time (the selected <bf> Switch </bf> key combination), and
you can obtain any alternate symbols defined for the
current national keyboard by holding down the 
<bf>Right Alt</bf> key (the selected <bf> Alternate Switch</bf> key)
while you type.



<bf>Options</bf>:

This section allows other options to be configured.
    
<itemize>
<item>
If the ``<bf>Beep</bf>'' option is activated,
the system will make an audible beep each time the keyboard map  changes.

<item>
Click on the <bf>Advanced</bf> button to open the 
<ref id="advanced" name="Advanced Options dialog">
for more options.

</itemize>

 <sect>International Keyboard -  Advanced Options<label id="advanced"><p>

    <img SRC=advanced.gif>

<bf>Emulate Caps Lock</bf>:

     For some keyboards (e.g. Russian, Greek) there are problems with
     the default <bf>CapsLock</bf> behavior. 
     If you activate this option, 
     you instruct the <it>International Keyboard</it>
     to emulate <bf>CapsLock</bf> in order to fix this problem. 
     The ``Caps Lock'' state (on or off) is then indicated by the color of the 
     keyboard-indicator button instead of
     the corresponding keyboard LED.

    <bf>World Menu</bf>:

      If you activate this option, 
      you can get a <it>International Keyboard</it>
       pop-up menu in any active window by pressing and holding
       down the <bf>Switch</bf>
       key combination  until the menu appears.

    <bf>Save Classes</bf>:

      If the the selection in the <bf>Input</bf> section (see below) is 
      ``<bf>Class</bf>'', you may
      activate the ``<bf>Save Classes</bf>'' option so that
      the  
      association of a given keyboard map with a given class
      of windows is automatically saved at the end of each KDE Session,
      and restored at the beginning of the next session. This means
      that, for example,  if  the
      the Russian keyboard map is selected for use in your <tt>Kedit</tt> 
      windows when you log out
      today, you will get it automatically in your <tt>Kedit</tt> windows
      when you log in tomorrow.



    <bf> Keyboard codes</bf>:
 
    The pull-down menu allows you  to choose to use 
    the keyboard codes native to your particular type of keyboard, instead of
    the <bf>X default codes</bf> used by the X Window system.

 

    <bf>Input</bf>:

      This determines how the keyboard maps are associated
      with different windows.
      You can select one of three choices:

      <itemize>
      <item>
        ``<bf>Global</bf>'' - 
       the current keyboard map applies to <bf>
       all</bf> windows.
      </item>
      <item>
       `` <bf>Window</bf>'' - 
        a separate keyboard map is associated with
        <bf>each top level window</bf>, and inherited by  each lower-level
        window created from
        within  it.
        When  the active window changes, the keyboard map will change
        to the map associated with the active window.
      </item>
      <item>
       ``<bf>Class</bf>'' - 
        a separate keyboard map is 
        associated with  <bf>each class
        of window</bf>
        (generally, the <it>class</it> of a window corresponds to
        to the application that opens it).  For example, if this
        selection is made, and you switch to the
        Russian keyboard
        in any window in which the <tt>Kedit</tt> program is running, 
        you will automatically also get the Russian keyboard in any
        other <tt>Kedit</tt> window, until you switch keyboards again.
      </item>
      </itemize>

(<ref id="general" name="Back to the ``General Settings'' main Help page">.)<p>





  <sect>International Keyboard - Style<label id="style" ><p>

    <p><img SRC=style.gif>

    In the <bf>Style</bf> dialog, You can customize the colors and
    font used by the <it>International Keyboard</it>  
    keyboard-indicator button that indicates which
    keyboard map is currently in use, and (by its color) shows whether
    the emulated <bf>Caps Lock</bf> is on or if the  <bf>Alternate Switch</bf>
    key is depressed.


<bf>Button Colors</bf>:

Clicking on one of the colored buttons opens the
``<bf>Select Color</bf>'' dialog, which allows
you to change the corresponding color used for the 
<it>International Keyboard</it> keyboard-indicator button.

    <itemize>
    <item> <bf>Foreground:</bf>
      Foreground color used for the text label.
    </item>

    <item><bf>Background:</bf>
      Normal Background color used for the text label.
      (<it> Not shown in screenshot!</it>.)
    </item>

    <item><bf>With CapsLock:</bf>
      Background color used for the text label 
      when <tt>Caps Lock</tt> emulation is
      selected and the <tt>Caps Lock</tt> key is activated.
    </item>

    <item><bf>With Alternate:</bf>
      Background color used for the text label while the <bf>Alt
      Switch</bf> key is held down to provide the alternate
      characters.
    </item>
    </itemize>

<bf>Button Font</bf>:

This section allows you to change the font used on the
keyboard-indicator button.
<itemize>
<item>
    Activate the ``<bf>Customize Font</bf>'' option if you
    wish to use custom or KDE wide fonts.   If this
    option is active, clicking the <bf>Change Font</bf>
    button will open the ``<bf>Select Font</bf>'' dialog.
</itemize>

  <sect>International Keyboard - Startup<label id="startup"><p>

  <img SRC=startup.gif>

  The  <bf>Startup</bf> dialog configures how  the 
  <it>International Keyboard</it>
  is started, and the placement of its keyboard-indicator
button.

<itemize>

<item> <bf>Autostart</bf>:
If this option is activated,
the <it>International Keyboard</it>  will be started automatically at the
beginning of each KDE session.


<item>  <bf>Docked</bf>:
   If this option is activated,  the
   keyboard-indicator button will be docked into the panel.

<item>  <bf>Place</bf>:
    If the ``<bf>Docked</bf>''  option
    is <bf>not</bf> active, the
    keyboard-indicator
    button will be placed at one of the four corners of the display.
    The  pull-down <bf>Place</bf> menu presents a list
    of choices for this location.
</itemize>

<sect>Creating a new National Keyboard<label id="create"><p>

  All system-wide keyboard files are stored in <tt>$KDEDIR/share/apps/kikbd</tt>
  and all personal keyboard files in <tt>$HOME/.kde/share/apps/kikbd</tt>.
  Each is identified by its file name excluding the <tt>.kimap</tt> extension. A
  personal keyboard file hides a system keyboard file having the same file name
  (not label).

  For creating a new keyboard map you should use one of the existing <tt>.kimap</tt>
  files as a template. Each keyboard file has two major sections.

  <enum>
  <item><bf>International Keyboard</bf><newline>
  In this section the following items can be defined:
    <itemize>
      <item><tt>Authors</tt>:a list of authors, separated by commas, 
        in the format "name last_name &lt email address&gt";
      </item>
      <item><tt>Comment</tt>**: a descriptive comment phrase for this keyboard;</item>
      <item><tt>Language</tt>**: the language this keyboard is for;</item>
      <item><tt>Charset</tt>: the charset this keyboard is for;</item>
      <item><tt>Locale</tt>: the locale this keyboard is for;</item>
      <item><tt>Label</tt>*: the label used by <tt>kikbd</tt> to identify this keyboard.</item>
    </itemize>
    * - required<newline>
    ** - can be translated to other languages
    <p>
  </item>
  <item><bf>KeyboardMap</bf><newline>
  This section contains mapping from default symbols to two, three or four
  new symbols in the form:
  <verb>
    keysym<num> = <default sym>,<sym1>,<sym2>,<sym3>,<sym4>,
  </verb>
  and mapping from key codes to symbols:
  <verb>
    keycode<num> = <key code>,<sym1>,<sym2>,<sym3>,<sym4>,
  </verb>

  Where <tt>num</tt> means any unique number, <tt>sym</tt> means symbol
  in the form of a hexadecimal number or a form interpreted by X11,
  <tt>keycode</tt> means the decimal code, and <tt>default sym</tt> means the
  default symbol for this key (before starting <tt>kikbd</tt>).
  The first two symbols <tt>sym1, sym2</tt> define the <it>national</it>
  symbols while <tt>sym3, sym4</tt> define <it>alternate</it> symbols.
  It is preferrable to use only <tt>keysym</tt> definitions. 
  <p>
  Additionally, in this section, you can also specify
  <it>CapsSymbols</it> as a list of Latin symbols, separated by commas.
  which <tt>kikbd</tt> should process during <tt>Caps Lock</tt> emulation.
  </item>
  </enum>

  After you create and test a new keyboard map, you could submit
  it to the KDE developer team, or directly to the author or
  maintainer of <tt>kikbd</tt>.

</sect>

<sect>Troubleshooting<p>

  <sect1>``Can not find symbol'' error.<p>
    This may happen if your X server has loaded non-Latin or unusual
    symbols before <tt>kikbd</tt> starts.
    <p>
    Beginning with version 1.0b1, you can
    predefine symbols in the
    <ref id="advanced" name="Advanced Options"> configuration dialog
    for fixing this problem. 
   (<it> This feature not currently available </it>) 
  </sect1>

  <sect1>Screen-saver password problems.<p>
    This problem might appear when your favorite screen saver starts
    while a national keyboard is active. The solution is to use KDE
    screen-savers with the default (first in the list) English keyboard.
    <tt>kikbd</tt> automatically switches the keyboard map to 
    the default, when one of
    KDE's screen-savers opens a password dialog.

    The other solution is to use Alternate Latin symbols in all 
    your keyboard maps.
    Then you can type a password using the <bf>Alternate Switch</bf> key.
  </sect1>

  <sect1>Bug reporting<p>
  Please report bugs at <htmlurl url="http://buglist.kde.org" 
	name="http://buglist.kde.org">
  </sect1>

</sect>

<sect>Authors<p>

International Keyboard is written by 
<htmlurl url="mailto:budnik@linserv.jinr.ru" 
	name="Alexander Budnik">,
and
<htmlurl url="mailto:dbouras@hol.gr" 
	name="Dimitrios P. Bouras">
<p>
</sect>

</article>



