movefasta/nixpkgs
0
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2025-07-13 21:50:33 +03:00
Code Activity

docs/xserver: document xserver.extraLayouts

Browse source
This commit is contained in:
rnhmjoj 2019-07-22 10:06:20 +02:00
parent 171d5c9200
commit 3effc55b5b
No known key found for this signature in database
GPG key ID: BFBAF4C975F76450
1 changed files with 130 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

130
nixos/doc/manual/configuration/x-windows.xml
View file

@ -157,4 +157,134 @@
versions. versions.
</para> </para>
</simplesect> </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 &quot;us-greek&quot;
{
include &quot;us(basic)&quot; // includes the base US keys
include &quot;level3(ralt_switch)&quot; // configures right alt as a third level switch
key &lt;LatA&gt; { [ a, A, Greek_alpha ] };
key &lt;LatB&gt; { [ b, B, Greek_beta ] };
key &lt;LatG&gt; { [ g, G, Greek_gamma ] };
key &lt;LatD&gt; { [ d, D, Greek_delta ] };
key &lt;LatZ&gt; { [ 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>&lt;alt&gt;+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 &quot;media&quot;
{
&lt;volUp&gt; = 123;
&lt;volDown&gt; = 456;
}
</programlisting>
<para>
Now use the newly define keycodes in <literal>media-sym</literal>:
</para>
<programlisting>
xkb_symbols &quot;media&quot;
{
key.type = &quot;ONE_LEVEL&quot;;
key &lt;volUp&gt; { [ XF86AudioLowerVolume ] };
key &lt;volDown&gt; { [ 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 &lt;filename&gt; &lt;content&gt;
</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> </chapter>