<?xml version="1.0" ?>
<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
"dtd/kdedbx45.dtd" [
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<article id="keyboard" lang="&language;">
<title>Keyboard</title>
<articleinfo>

<authorgroup>
<author>&Mike.McBride; &Mike.McBride.mail;</author>
<author>&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<date>2020-12-05</date>
<releaseinfo>Plasma 5.21</releaseinfo>

<keywordset>
<keyword>KDE</keyword>
<keyword>Plasma</keyword>
<keyword>System Settings</keyword>
<keyword>keyboard</keyword>
</keywordset>
</articleinfo>

<para>This module allows you to choose how your keyboard works.</para>

<para>There are three tabs in this module.</para>

<sect1 id="hardware">
<title>The Hardware tab</title>
<para>The actual effect of setting these options depends upon the
features provided by your keyboard hardware and the X server on which
&plasma; is running.  As an example, you may find that changing the key
click volume has no effect because that feature is not available on your
system. </para>

<variablelist>
<varlistentry>
<term><guilabel>Keyboard model:</guilabel></term>
<listitem>
<para>
Here you can set your keyboard model. This setting is independent of your
keyboard layout and refers to the &quot;hardware&quot; 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 &quot;104-key&quot; models, which is
probably what you want if you do not know what kind of keyboard you have.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>NumLock on Plasma Startup</guilabel></term>
<listitem>
<para>You can choose to either always <guilabel>Turn on</guilabel> or
<guilabel>Turn off</guilabel> the NumLock when &plasma; starts, or you can
choose to have &plasma; leave NumLock at whatever it was set to before &plasma;
started up.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>When a key is held:</guilabel></term>
<listitem>
<para>It is possible to select one of the tree options here, namely</para>
<variablelist>
<varlistentry>
<term><guilabel>Show accented and similar characters</guilabel></term>
<listitem>
<para>If this option is selected, when a key is held down while entering text, a popup is shown which lets one choose between various accented forms of the character.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Do nothing</guilabel></term>
<listitem>
<para>This option allows you to turn off any activities when you pressing and holding down the keys.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Repeat the key</guilabel></term>
<listitem>
<para>When this option is selected, pressing and holding down a key
emits the same character repeatedly until the key is released.  Pressing
and holding the key will have the same effect as pressing it multiple
times in succession.</para>
<tip><para> Almost all users will want to have this option enabled, because it
makes navigating through documents with the arrow keys significantly
easier. </para></tip>
</listitem>
</varlistentry>
</variablelist>

<variablelist>
<varlistentry>
<term><guilabel>Delay</guilabel></term>
<listitem>
<para>This option allows you to set the delay after which a pressed
key will start generating keycodes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Rate</guilabel></term>
<listitem>
<para>This option allows you to set the rate at which keycodes are
generated while a key is pressed.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Type some characters into the <guilabel>Test area</guilabel> text box to
verify the settings.</para>
<para>Many computers won't support this function.</para>

</listitem>
</varlistentry>

</variablelist>
</sect1>

<sect1 id="layouts">
<title>The Layouts tab</title>
<para>This tab lets you choose what keyboard layouts you want to use, what
indicator you want in the system tray, how you want to switch and which
shortcuts you will use.</para>

<variablelist>
<varlistentry>
<term><guilabel>Layout Indicator</guilabel></term>
<listitem>
<para>You can choose to <guilabel>Show layout indicator</guilabel>
which will show the language iso name in the system tray. You can choose to
show the indicator even if you have a single layout enabled
and you can show the language flag instead of only the ISO code by checking
<guilabel>Show flag</guilabel>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Switching Policy</guilabel></term>
<listitem>
<para>If you select <guilabel>Application</guilabel> or
<guilabel>Window</guilabel> switching policy, changing the keyboard layout will
only affect the current application or window. <guilabel>Global</guilabel> will
change the keyboard layout globally and <guilabel>Desktop</guilabel> will change
it only for the current virtual desktop.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Shortcuts for Switching Layout</guilabel></term>
<listitem>
<para><guilabel>Main shortcuts</guilabel> is a shortcut for switching
layouts which is handled by X.org. <guilabel>3rd level shortcuts</guilabel> is a
shortcut for switching to a third level of the active layout (if it has one)
which is handled by X.org. It allows modifier-only shortcuts.
<guilabel>Alternative shortcut</guilabel> is a shortcut for switching layouts
which is handled by &plasma;. It does not support modifier-only shortcuts and also
may not work in some situations (&eg; if popup is active or from screensaver).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Configure layouts</guilabel></term>
<listitem>
<para>If you check <guilabel>Configure layouts</guilabel> you will be able to
add and remove keyboard layouts in order to switch between them when you need.
</para>
<para>Clicking on <guibutton>Add</guibutton> will open a dialog where you
will be able to choose the new keyboard layout you want to add as well as its
variant, label and shortcut.
</para>
<para>
The list of layouts right to the <guilabel>Layout</guilabel> label in the
<guilabel>Add Layout</guilabel> dialog can be narrowed down using
<guilabel>Limit selection by language</guilabel> drop-down list. You
can click on <guibutton>Preview</guibutton> button to preview chosen layout
in a separate window.
</para>
<para>You can order the layouts with the up and down buttons, the top one being
the default one.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Spare layouts</guilabel></term>
<listitem>
<para>This option can be enabled only if you have more than two layouts.</para>
<para>Spare layouts allow to toggle between small number of layouts easily
while keeping more layouts handy close by. For example you might use 3
languages: English, Ukrainian and German but first two are used often
and third one just occasionally. In this case you can configure first
two as main layouts (setting <guilabel>Main layout count</guilabel>: 2)
and German one as spare one - when you toggle with
keyboard and left mouse button the switch will happen between main
layouts only but you can always choose 3rd layout with context menu.</para>
<para>When spare layout is chosen it replaces the last main layout (this is
done for technical reasons, usually global shortcuts work based on the
1st active layout so it's more reliable to preserve the 1st layout when
allowing to activate spare layouts).</para>
<!-- context menu ?-->
<para>As X.org only allows to have 4 layouts to switch <quote>spare layouts</quote> feature
also allows to overcome this limitation: user can have up to 4 main
layouts (managed by X.org) but 4 more spare layouts allowed (managed by
layout switcher). Thus user can conveniently work with up to total of 8
layouts (although the 4 spare layouts limit can be raised in the future).
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="advanced">
<title>The Advanced tab</title>
<para>In this tab, if you check <guilabel>Configure keyboard options</guilabel>
you will then be able to set a few options regarding some special keys settings. You can
expand these options by clicking on the &gt; symbol on the left of the option
then you choose your setting in the expanded list.</para>
<para>This is a &GUI; to help creating custom keyboard layouts for &X11; using XKB.
</para>
<para>For more information please refer to the <emphasis>Links</emphasis> section on the
<ulink url="https://www.freedesktop.org/wiki/Software/XKeyboardConfig">XKeyboardConfig
page on freedesktop.org</ulink>.
</para>
</sect1>
</article>
