# International Keyboard Handbook

Alexander
Budnik

    budnik@linserv.jinr.ru

Dimitrios
P.
Bouras

    dbouras@hol.gr

Duncan
Document revision

    duncan@kde.org

20/08/1999
1.02.04

This Handbook describes International Keyboard Version 1.0b4

KDE

## Introduction

KDE International Keyboard (`kikbd`) is designed to help type national symbols different from the default Latin symbols under X11.

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

`kikbd` uses the `xmodmap` 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, `kikbd` can also maintain different keyboard maps for different windows or applications (using Window or Class input styles respectively).

## Installation

Installation from sources follows the usual procedure :-)

            % ./configure
            % make
            % make install

You need at least KDE 1.0 to successfully compile `kikbd`. Starting with KDE version 1.1, `kikbd` is included in the `kdebase` package.

## National Keyboard

For each language or national keyboard, `kikbd` supports a keyboard map 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 alternate symbols.

For typing alternate symbols you have to set up a choice of a special Alternate Switch key in the `kikbd` configuration; for details, see the Personal Configuration section. Normally the first symbol is obtained by typing without any modifier keys pressed, the second symbol when you type with the Shift held down, the third symbol when you type with the Alternate Switch held key down, and the fourth symbol when you type with the Alternate Switch + Shift keys both held down.

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

If a keyboard for your language is missing see section Creating a new National Keyboard.

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

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

To run `kikbd`, go to the System menu and choose ``International Keyboard Layout''.

## Configuring the KDE International Keyboard.

There are three configuration screens for the KDE International Keyboard.

- The General settings screen, for selecting the keyboard map, and hot keys. This also accesses the Advanced Options screen.

- The Style screen for configuring the fonts and colors used by the International Keyboard keyboard-indicator button.

- The Startup screen for configuring how the International Keyboard is started, and the placement of the keyboard-indicator button.

## International Keyboard - General settings

The KDE International Keyboard program (`kikbd`) 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 International Keyboard Layout item in the System 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 Switch ``hotkey'' combination, or by clicking on the keyboard-indicator button that is present whenever the International Keyboard program is running.

The General Settings screen configures the keyboard maps and ``hotkeys''.

Keyboard maps:

Your personal list of national keyboard maps is shown in the box. The first entry is the default keyboard map, used by International Keyboard when it starts. When you start the International Keyboard 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 `En` - US English Language.)

Use the buttons at the right to control your keyboard map list.

- Click on the Add button to add entries to the list of keyboard maps. This opens the Add Keyboard screen which has a pull-down list of available keyboard maps, and gives information about the keyboard you select from it. Click on its OK button to add the chosen keyboard map to your personal list, or on Cancel to close the screen without changing your list.

- Click on the Delete button to remove the selected (highlighted) keyboard map from your personal list.

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

- Click on the Info button to view the Keyboard Map Information screen about the selected keyboard.

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

Switch and Alt Switch:

This section allows you to choose the ``hotkey'' combinations used by International Keyboard for the Switch and Alternate Switch keys.

The box on the left shows the key combination chosen for the Switch key .

- Pressing the Switch key combination switches the keyboard map to the the next one in your personal list of keyboard maps (or between the default and the highlighted (``hot'') map, if the ``use hotlist'' box is checked).

The box on the right shows the key chosen as the Alternate Switch key. This acts as a second shift-type key for accessing any alternate characters defined in the keyboard map.

- The ``lower-case'' alternate characters in the keyboard map for the current national keyboard are obtained if the key is typed with the Alternate Switch key held down, and the ``upper-case'' alternate characters are obtained if the key is typed with both the Alternate Switch and the Shift held down.

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 Right Ctrl and Right Shift keys at the same time (the selected Switch key combination), and you can obtain any alternate symbols defined for the current national keyboard by holding down the Right Alt key (the selected Alternate Switch key) while you type.

Options:

This section allows other options to be configured.

- If the ``Beep'' box is checked, the system will make an audible beep each time the keyboard map changes.

- Click on the Advanced button to open the Advanced Options screen for more options.

## International Keyboard - Advanced Options

Emulate Caps Lock:

For some keyboards (e.g. Russian, Greek) there are problems with the default CapsLock behavior. If you check this box, you instruct the International Keyboard to emulate CapsLock 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.

World Menu:

If you check this box, You can get a International Keyboard pop-up menu in any active window by pressing and holding down the Switch key combination until the menu appears.

Save Classes:

If the the selection in the Input section (see below) is ``Class'', you may check the ``Save Classes'' box 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 `Kedit` windows when you log out today, you will get it automatically in your `Kedit` windows when you log in tomorrow.

Keyboard codes:

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

Input:

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

- ``Global'' - the current keyboard map applies to all windows.

- `` Window'' - a separate keyboard map is associated with each top level window, 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.

- ``Class'' - a separate keyboard map is associated with each class of window (generally, the class 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 `Kedit` program is running, you will automatically also get the Russian keyboard in any other `Kedit` window, until you switch keyboards again.

(Back to the ``General Settings'' main Help page.)

## International Keyboard - Style

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

Button Colors:

Clicking on one of the colored buttons opens the ``Select Color'' menu screen, which allows you to change the corresponding color used for the International Keyboard keyboard-indicator button.

- Foreground: Foreground color used for the text label.

- Background: Normal Background color used for the text label. ( Not shown in screenshot!.)

- With CapsLock: Background color used for the text label when `Caps Lock` emulation is selected and the `Caps Lock` key is activated.

- With Alternate: Background color used for the text label while the Alt Switch key is held down to provide the alternate characters.

Button Font:

This section allows you to change the font used on the keyboard-indicator button.

- Check the ``Customize Font'' box if you wish to use custom or KDE wide fonts. If this box is checked, clicking the Change Font button will open the ``Select Font'' menu screen.

## International Keyboard - Startup

The Startup screen configures how the International Keyboard is started, and the placement of its keyboard-indicator button.

- Autostart: If this box is checked, the International Keyboard will be started automatically at the beginning of each KDE session.

- Docked: If this box is checked, the keyboard-indicator button will be docked into the panel.

- Place: If the ``Docked'' box is not checked, the keyboard-indicator button will be placed at one of the four corners of the display. The pull-down Place menu presents a list of choices for this location.

## Creating a new National Keyboard

All system-wide keyboard files are stored in `$KDEDIR/share/apps/kikbd` and all personal keyboard files in `$HOME/.kde/share/apps/kikbd`. Each is identified by its file name excluding the `.kimap` 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 `.kimap` files as a template. Each keyboard file has two major sections.

1. International Keyboard In this section the following items can be defined:

   - `Authors`:a list of authors, separated by commas, in the format "name last&lowbar;name < email address>";

   - `Comment`**: a descriptive comment phrase for this keyboard;

   - `Language`**: the language this keyboard is for;

   - `Charset`: the charset this keyboard is for;

   - `Locale`: the locale this keyboard is for;

   - `Label`*: the label used by `kikbd` to identify this keyboard.

   * - required ** - can be translated to other languages

2. KeyboardMap This section contains mapping from default symbols to two, three or four new symbols in the form:

             keysym<num> = <default sym>,<sym1>,<sym2>,<sym3>,<sym4>,

   and mapping from key codes to symbols:

             keycode<num> = <key code>,<sym1>,<sym2>,<sym3>,<sym4>,

   Where `num` means any unique number, `sym` means symbol in the form of a hexadecimal number or a form interpreted by X11, `keycode` means the decimal code, and `default sym` means the default symbol for this key (before starting `kikbd`). The first two symbols `sym1, sym2` define the national symbols while `sym3, sym4` define alternate symbols. It is preferrable to use only `keysym` definitions.

   Additionally, in this section, you can also specify CapsSymbols as a list of Latin symbols, separated by commas. which `kikbd` should process during `Caps Lock` emulation.

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

## Troubleshooting

### ``Can not find symbol'' error.

This may happen if your X server has loaded non-Latin or unusual symbols before `kikbd` starts.

Beginning with version 1.0b1, you can predefine symbols in the Advanced Options configuration screen for fixing this problem.

### Screen-saver password problems.

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. `kikbd` 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 Alternate Switch key.

### Bug reporting

Please report bugs at http://buglist.kde.org

## Authors

International Keyboard is written by mailto:budnik@linserv.jinr.ru">Alexander Budnik, and mailto:dbouras@hol.gr">Dimitrios P. Bouras