docs/xserver: document xserver.extraLayouts
This commit is contained in:
rnhmjoj
parent
171d5c9200
commit
3effc55b5b
1 changed files with 130 additions and 0 deletions
|
|
@ -157,4 +157,134 @@
|
|||
versions.
|
||||
</para>
|
||||
</simplesect>
|
||||
<simplesect xml:id="custom-xkb-layouts">
|
||||
<title>Custom XKB layouts</title>
|
||||
<para>
|
||||
It is possible to install custom
|
||||
<link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension">
|
||||
XKB
|
||||
</link>
|
||||
keyboard layouts using the option
|
||||
<option>
|
||||
<link linkend="opt-services.xserver.extraLayouts">
|
||||
services.xserver.extraLayouts
|
||||
</link>
|
||||
</option>.
|
||||
As a first example, we are going to create a layout based on the basic US
|
||||
layout, with an additional layer to type some greek symbols by pressing the
|
||||
right-alt key.
|
||||
</para>
|
||||
<para>
|
||||
To do this we are going to create a <literal>us-greek</literal> file
|
||||
with a <literal>xkb_symbols</literal> section.
|
||||
</para>
|
||||
<programlisting>
|
||||
xkb_symbols "us-greek"
|
||||
{
|
||||
include "us(basic)" // includes the base US keys
|
||||
include "level3(ralt_switch)" // configures right alt as a third level switch
|
||||
|
||||
key <LatA> { [ a, A, Greek_alpha ] };
|
||||
key <LatB> { [ b, B, Greek_beta ] };
|
||||
key <LatG> { [ g, G, Greek_gamma ] };
|
||||
key <LatD> { [ d, D, Greek_delta ] };
|
||||
key <LatZ> { [ z, Z, Greek_zeta ] };
|
||||
};
|
||||
</programlisting>
|
||||
<para>
|
||||
To install the layout, the filepath, a description and the list of
|
||||
languages must be given:
|
||||
</para>
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.extraLayouts"/>.us-greek = {
|
||||
description = "US layout with alt-gr greek";
|
||||
languages = [ "eng" ];
|
||||
symbolsFile = /path/to/us-greek;
|
||||
}
|
||||
</programlisting>
|
||||
<note>
|
||||
<para>
|
||||
The name should match the one given to the
|
||||
<literal>xkb_symbols</literal> block.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
The layout should now be installed and ready to use: try it by
|
||||
running <literal>setxkbmap us-greek</literal> and type
|
||||
<literal><alt>+a</literal>. To change the default the usual
|
||||
<option>
|
||||
<link linkend="opt-services.xserver.layout">
|
||||
services.xserver.layout
|
||||
</link>
|
||||
</option>
|
||||
option can still be used.
|
||||
</para>
|
||||
<para>
|
||||
A layout can have several other components besides
|
||||
<literal>xkb_symbols</literal>, for example we will define new
|
||||
keycodes for some multimedia key and bind these to some symbol.
|
||||
</para>
|
||||
<para>
|
||||
Use the <emphasis>xev</emphasis> utility from
|
||||
<literal>pkgs.xorg.xev</literal> to find the codes of the keys of
|
||||
interest, then create a <literal>media-key</literal> file to hold
|
||||
the keycodes definitions
|
||||
</para>
|
||||
<programlisting>
|
||||
xkb_keycodes "media"
|
||||
{
|
||||
<volUp> = 123;
|
||||
<volDown> = 456;
|
||||
}
|
||||
</programlisting>
|
||||
<para>
|
||||
Now use the newly define keycodes in <literal>media-sym</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
xkb_symbols "media"
|
||||
{
|
||||
key.type = "ONE_LEVEL";
|
||||
key <volUp> { [ XF86AudioLowerVolume ] };
|
||||
key <volDown> { [ XF86AudioRaiseVolume ] };
|
||||
}
|
||||
</programlisting>
|
||||
<para>
|
||||
As before, to install the layout do
|
||||
</para>
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.extraLayouts"/>.media = {
|
||||
description = "Multimedia keys remapping";
|
||||
languages = [ "eng" ];
|
||||
symbolsFile = /path/to/media-key;
|
||||
keycodesFile = /path/to/media-sym;
|
||||
};
|
||||
</programlisting>
|
||||
<note>
|
||||
<para>
|
||||
The function <literal>pkgs.writeText <filename> <content>
|
||||
</literal> can be useful if you prefer to keep the layout definitions
|
||||
inside the NixOS configuration.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
Unfortunately, the Xorg server does not (currently) support setting a
|
||||
keymap directly but relies instead on XKB rules to select the matching
|
||||
components (keycodes, types, ...) of a layout. This means that components
|
||||
other than symbols won't be loaded by default. As a workaround, you
|
||||
can set the keymap using <literal>setxkbmap</literal> at the start of the
|
||||
session with:
|
||||
</para>
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.xserver.displayManager.sessionCommands"/> = "setxkbmap -keycodes media";
|
||||
</programlisting>
|
||||
<para>
|
||||
To learn how to write layouts take a look at the XKB
|
||||
<link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts">
|
||||
documentation
|
||||
</link>. More example layouts can also be found
|
||||
<link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples">
|
||||
here
|
||||
</link>.
|
||||
</para>
|
||||
</simplesect>
|
||||
</chapter>
|
||||
|
|
|
|||
Loading…
Reference in a new issue