# The &kxkb; Handbook

## Introduction

&kxkb; is the &kde; keyboard layout switching utility. It is based on X11 xkb extension and allows to use different keyboard layouts for inputting text. &kxkb; features keyboard layout indicator.

## Using &kxkb;

### Getting Started

&kxkb; starts automatically and stays in the system tray as a flag with 2 or 3 letter abbreviation of layout name on top of it if more than one layout is defined or Show indicator for single layout option is turned on.

When &kxkb; is running you can change layouts by clicking on its tray icon with the mouse or pressing keyboard shortcut. Keyboard shortcut or mouse click will switch to the next layout or alternatively you can &RMB; click the &kxkb; icon and select layout from the list.

&RMB; clicking on the &kxkb; icon you can start its configuration by selecting Configure... or by opening &systemsettings; and selecting Regional & Language Keyboard Layout. Alternatively, you can start it by typing `kcmshell4 keyboard_layout` from the terminal.

## Configuring &kxkb;

### General Information

&kxkb; configuration consists of three tabs: Layout, Switching Options, and Advanced. The first one defines layouts you want to use and their options (variant, display label etc.), second defines how the layout switching is done, including which shortcut is used and whether the layout should be remembered for each window, application &etc;. Third tab allows to set options for Xkb extension. These options are properties of X.org and are not handled in any way by &kxkb; - it just sets them up.

&kxkb; can work in two modes: full switching support and indicator only. First mode allows user to configure layouts, shortcuts and other options, while in the second mode &kxkb; just displays current layout, assuming configuring and switching is done by X itself.

&kxkb; configuration does not change anything in X.org configuration files. If Enable keyboard layouts is selected Layout settings from X.org configuration will be overridden and if Reset old options is turned on Xkb options will be overriden too.

If Reset old options is turned off, xkb options selected in the configuration will be merged with currently active ones, &ie; the ones from the X.org configuration file plus any set later.

If Enable keyboard layouts is selected &kxkb; initializes the layouts with `setxkbmap` command. In the configuration window you can see the command line to be executed during initialization. The same is true for xkb options. These commands can be useful for troubleshooting or customizing xkb configuration.

### Layout Configuration

In layout configuration the list of available layouts is on your left. You have to choose each layout you want to use and add them (one by one) to the list of active layouts on the right. You can also change the order in which active layouts will be switched when toggled by keyboard shortcut or mouse button. The first layout in the list becomes the default layout.

Some layouts have several variants. Layout variants usually represent different key maps for the same language. For example, Ukrainian layout might have four variants: basic, winkeys (as in &Windows;), typewriter (as in typewriters) and phonetic (each Ukrainian letter is placed on a transliterated Latin one). If your layout is a multi-variant one you can choose the variant in the combo box below the active layouts list.

You can also change the label you want on the indicator when layout selected if you don't like default one.

Keyboard model setting is independent of your keyboard layout and refers to the "hardware" model, &ie; the way your keyboard is manufactured. Modern keyboards that come with your computer usually have two extra keys and are referred to as "104-key" models, which is probably what you want if you don't know what kind of keyboard you have.

If you leave the active layout list empty, keyboard layouts will be disabled

### Switching Options

Here you can choose a switching policy for keyboard layout. By default it's Global, meaning all applications will share the same current layout. Application means each application will have its own layout and switching layout while you are working with one application will not affect the layout for any others. Window will make every window have its own layout even if they belong to the same program and Desktop allows you to have one layout per desktop.

In shortcuts section you can choose which shortcut is used for switching layouts. Shortcut can be modifier-only key combination (&ie; &Ctrl;&Shift;, non-modifier keys (&ie; &Ctrl;&Shift;K) or you can use both.

#### Modifier-only shortcuts

These shortcuts are handled by X.org (not &Qt;/&kde;) and are configured in Advanced tab. Availabe list of shortcuts is fixed but you can define your own if you know how to change xkb rules and maps. Just note if you hack xkb maps don't forget to change xorg.xml rules file as that's where &kxkb; takes the configuration information from.

The disadvantage of this approach is that the switching is done on key press not key release so ⪚ if you configure shortcut to be &Ctrl;&Shift; your other shortcuts which start with this combination may stop working. See X.org bug 865

If your layout has 3d level of characters you can also configure the shortcut for it here.

#### Standard shortcuts

These shortcuts are handled by &Qt;/&kde; and allow more flexible key combinations.

The disadvantage of this approach is that the standard shortcuts won't work if you have some popup window (like drop-down combobox) open.

### Advanced

Xkb options allow you to select behavior of your keyboard. These options are not handled by &kxkb; and just passed to xkb extension.

## Troubleshooting

### Common Problems

If you switch to some layout and you cannot see some characters from your layout as you type, please check your local settings, ⪚ `~/.i18n` or `/etc/sysconfig/i18n`, locale you have before starting &kde; applications must have an encoding which contains characters from your layout. Recommended encoding is UTF-8 which should work for most languages.

## Files and Layout Descriptions

### xkb Files and Layouts

All available keyboard layouts, variants and options are described in `/usr/share/X11/rules/xorg.xml`, and the layouts themselves can be found in `/usr/share/X11/symbols`. Note that the location of these files may depend on your operating system and distribution.

## Credits and Licenses

&kxkb; is currently developed and maintained by &Andriy.Rysin; &Andriy.Rysin.mail;. Several other people have worked on kxkb:

- Shaheed Haque srhaque@iee.org

- Ilya Konstantinov kde-devel@future.galanet.net

&underFDL; &underGPL;