<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" 
"dtd/kdex.dtd" [
  <!ENTITY kappname "&kxkb;">
  <!ENTITY package "kdebase">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<book lang="&language;">
<bookinfo>
<title>The &kxkb; Handbook</title>

<authorgroup>
<author>
&Andriy.Rysin; &Andriy.Rysin.mail;
</author>

<othercredit role="developer">
&Andriy.Rysin; &Andriy.Rysin.mail;
<!-- <contrib>Developer</contrib> -->
</othercredit>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<copyright>
<year>2003,2008</year>
<holder>&Andriy.Rysin;</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2008-04-12</date>
<releaseinfo>2.00.00</releaseinfo>

<abstract><para>&kxkb; is a keyboard layout switching 
utility based on X11 xkb extension.</para></abstract> 

<keywordset>
<keyword>KDE</keyword>
<keyword>kxkb</keyword>
<keyword>keyboard</keyword>
<keyword>layout</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>&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.
</para>

</chapter>

<chapter id="usingthekxkb">
<title>Using &kxkb;</title>

<sect1 id="getting-started">
<title>Getting Started</title>

<para>&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 <guilabel>Show indicator for single
layout</guilabel> option is turned on.</para>

<para>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.</para>

<para>&RMB; clicking on the &kxkb; icon you can start its
configuration by selecting <guimenuitem>Configure...</guimenuitem> or
by opening &systemsettings; and selecting <guilabel>Regional &amp; 
Language</guilabel> <guilabel>Keyboard Layout</guilabel>. Alternatively, you can start it by
typing <command>kcmshell4 keyboard_layout</command> from the terminal.</para>
</sect1>
</chapter>

<chapter id="configuringkxkb">
<title>Configuring &kxkb;</title>

<sect1 id="general-config">
<title>General Information</title>
<para>
&kxkb; configuration consists of three tabs: <guilabel>Layout</guilabel>, <guilabel>Switching Options</guilabel>, and 
<guilabel>Advanced</guilabel>. 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 wether 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.
</para>
<para>
&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.
</para>
<note><para>
&kxkb; configuration does not change anything in X.org configuration 
files. If <guilabel>Enable keyboard layouts</guilabel> is selected Layout settings 
from X.org configuration will be overridden and if <guilabel>Reset old options</guilabel> 
is turned on Xkb options will be overriden too.
</para></note>
<note><para>
If <guilabel>Reset old options</guilabel> 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.
</para></note>
<para>
If <guilabel>Enable keyboard layouts</guilabel> is selected &kxkb; initializes 
the layouts with <command>setxkbmap</command> 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.
</para>
</sect1>

<sect1 id="layout-config">
<title>Layout Configuration</title>
<para>
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.
</para>
<para>
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.
</para>
<para>
You can also change the label you want on the indicator when layout selected 
if you don't like default one.
</para>
<para>
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.
</para>
<note>
<para>
If you leave the active layout list empty, keyboard layouts will be disabled
</para>
</note>
</sect1>
<sect1 id="switching-config">
<title>Switching Options</title>
<para>
Here you can choose a switching policy for keyboard layout. By default it's 
<guilabel>Global</guilabel>, meaning all applications will share the same current
layout. <guilabel>Application</guilabel> 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. <guilabel>Window</guilabel> will make every window
have its own layout even if they belong to the same program and <guilabel>Desktop</guilabel> 
allows you to have one layout per desktop.
</para>
<para>
In shortcuts section you can choose which shortcut is used for switching layouts.
Shortcut can be modifier-only key combination (&ie; <keycombo action="simul">&Ctrl;&Shift;</keycombo>, non-modifier keys
(&ie; <keycombo action="simul">&Ctrl;&Shift;<keycap>K</keycap></keycombo>) or you can use both. 
</para>
<sect2 id="modifier-only-keys">
<title>Modifier-only shortcuts</title>
<para>
These shortcuts are handled by X.org (not &Qt;/&kde;) and are configured in <guilabel>Advanced</guilabel> 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.
</para>
<note>
<para>
The disadvantage of this approach is that the switching is done on key press not 
key release so &eg; if you configure shortcut to be <keycombo action="simul">&Ctrl;&Shift;</keycombo> your other shortcuts which start with this combination may stop working. See <ulink url="http://bugs.freedesktop.org/show_bug.cgi?id=865">X.org bug 865</ulink>
</para>
</note>
<para>
If your layout has 3d level of characters you can also configure the shortcut for it here.
</para>
</sect2>
<sect2 id="non-modifier-only-keys">
<title>Standard shortcuts</title>
<para>
These shortcuts are handled by &Qt;/&kde; and allow more flexible key combinations.
</para>
<note>
<para>
The disadvantage of this approach is that the standard shortcuts won't work if
you have some popup window (like drop-down combobox) open.
</para>
</note>
</sect2>
</sect1>

<sect1 id="xkboptions-config">
<title>Advanced</title>
<para>
Xkb options allow you to select behavior of your keyboard. These options are not 
handled by &kxkb; and just passed to xkb extension.
</para>
</sect1>

</chapter>

<chapter id="kxkbtroubleshooting">
<title>Troubleshooting</title>

<sect1 id="troubles">
<title>Common Problems</title>

<para>If you switch to some layout and you cannot see some characters
from your layout as you type, please check your local settings, &eg;
<filename>~/.i18n</filename> or
<filename>/etc/sysconfig/i18n</filename>, 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.
</para>

</sect1>
</chapter>

<chapter id="xkb-files">
<title>Files and Layout Descriptions</title>
<sect1 id="xkb-files-and-layouts">
<title><application>xkb</application> Files and Layouts</title>

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

</sect1>

</chapter>

<chapter id="credits-and-licenses">
<title>Credits and Licenses</title>

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

<itemizedlist>
<listitem><para>Shaheed Haque <email>srhaque@iee.org</email></para></listitem>
<listitem><para>Ilya Konstantinov <email>kde-devel@future.galanet.net</email>
</para></listitem>
</itemizedlist>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;
&underGPL;

</chapter>

</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->