Difference between revisions of "Extra keyboard keys in Xorg"

From ArchWiki
Jump to: navigation, search
m (related)
m (style)
Line 15: Line 15:
 
When we are in a graphical environment we may want a key to print a special character or execute a command. There are some ways of doing that and they are covered in this HOWTO.
 
When we are in a graphical environment we may want a key to print a special character or execute a command. There are some ways of doing that and they are covered in this HOWTO.
  
{{Box Note |This article assumes that your keys already have keycodes and that you know these codes, if not, see the [[Extra Keyboard Keys]] article where it is explained.}}
+
{{Note|This article assumes that your keys already have keycodes and that you know these codes, if not, see the [[Extra Keyboard Keys]] article where it is explained.}}
 +
 
 +
== Map keycodes to symbols ==
 +
 
 +
=== Introduction ===
  
==Map keycodes to symbols==
 
===Introduction===
 
 
The most traditional and proficient way to make a key output a character when you are in X is to use xmodmap. Xmodmap is roughly the X equivalent of ''loadkeys'': it reads a file containing some directives. As ''loadkeys'', it can be used to modify many aspects of the behaviour of your keyboard (such as modifiers, etc.), but I will not cover these aspects in this article. The only kind of directive I am interested in here associates an X keycode to a keysym. ''xmodmap'' is included in the {{pkg|xorg-server-utils}} package in the [[Official Repositories]].
 
The most traditional and proficient way to make a key output a character when you are in X is to use xmodmap. Xmodmap is roughly the X equivalent of ''loadkeys'': it reads a file containing some directives. As ''loadkeys'', it can be used to modify many aspects of the behaviour of your keyboard (such as modifiers, etc.), but I will not cover these aspects in this article. The only kind of directive I am interested in here associates an X keycode to a keysym. ''xmodmap'' is included in the {{pkg|xorg-server-utils}} package in the [[Official Repositories]].
  
===Step 1: Create the xmodmap file===
+
=== Step 1: Create the xmodmap file ===
 +
 
 
In this file, you have to list the keycode directives, with the following syntax:
 
In this file, you have to list the keycode directives, with the following syntax:
 +
 
  keycode <Xkeycode> = <keysym>
 
  keycode <Xkeycode> = <keysym>
 +
 
The list of X keysyms can be read in {{ic|/usr/include/X11/keysymdef.h}}. Anyway, most of them are intuitive. Let us say that the X keycode of my hotkey is 239. If I want it to output a literal 'e', I will write the following directive:
 
The list of X keysyms can be read in {{ic|/usr/include/X11/keysymdef.h}}. Anyway, most of them are intuitive. Let us say that the X keycode of my hotkey is 239. If I want it to output a literal 'e', I will write the following directive:
 +
 
  keycode 239 = e
 
  keycode 239 = e
 +
 
If I want it to output the symbol of the American currency, I will write the following directive:
 
If I want it to output the symbol of the American currency, I will write the following directive:
 +
 
  keycode 239 = dollar
 
  keycode 239 = dollar
  
Line 32: Line 40:
  
 
An example {{ic|~/.Xmodmap}}:
 
An example {{ic|~/.Xmodmap}}:
 +
 
  keycode 160 = XF86AudioMute
 
  keycode 160 = XF86AudioMute
 
  keycode 176 = XF86AudioRaiseVolume
 
  keycode 176 = XF86AudioRaiseVolume
Line 38: Line 47:
 
Multimedia programs such as Rhythmbox and Exaile are designed to work with keys assigned to XF86 Symbols out-of-the-box, without the need to configure a third-party application.
 
Multimedia programs such as Rhythmbox and Exaile are designed to work with keys assigned to XF86 Symbols out-of-the-box, without the need to configure a third-party application.
  
===Step 2: Testing===
+
=== Step 2: Testing ===
 +
 
 
Finally I have to source the file with xmodmap:
 
Finally I have to source the file with xmodmap:
 +
 
  $ xmodmap ~/.Xmodmap
 
  $ xmodmap ~/.Xmodmap
  
===Step 3: Making it permanent===
+
=== Step 3: Making it permanent ===
 +
 
 
Obviously, this will work only for the current X session, use [[xprofile]] to make it permanent.
 
Obviously, this will work only for the current X session, use [[xprofile]] to make it permanent.
  
==Map keycodes to actions==
+
== Map keycodes to actions ==
  
 
{{Accuracy|''keycodes'' are mapped to ''keysyms'' and then ''keysyms'' can be mapped to actions}}
 
{{Accuracy|''keycodes'' are mapped to ''keysyms'' and then ''keysyms'' can be mapped to actions}}
Line 54: Line 66:
 
* The quicker way using a third-party program to do everything in GUI, such as the Gnome Control Center or [[Keytouch]].
 
* The quicker way using a third-party program to do everything in GUI, such as the Gnome Control Center or [[Keytouch]].
  
===Using your Desktop Environment tools===
+
=== Using your Desktop Environment tools ===
====Gnome====
+
 
 +
==== Gnome ====
 +
 
 
Gnome Control Center is quite complete for the extra keyboard keys management. In fact it can directly detect scancodes which means that it can map any key seen by the kernel.
 
Gnome Control Center is quite complete for the extra keyboard keys management. In fact it can directly detect scancodes which means that it can map any key seen by the kernel.
  
====KDE====
+
==== KDE ====
 +
 
 
Keyboard shortcuts can be configured in '''System Settings''' -> '''Shortcuts and Gestures'''.
 
Keyboard shortcuts can be configured in '''System Settings''' -> '''Shortcuts and Gestures'''.
  
====Xfce4====
+
==== Xfce4 ====
 +
 
 
You can change the keyboard shortcuts in Keyboard Settings, which can be run using {{Ic|xfce4-keyboard-settings}}.
 
You can change the keyboard shortcuts in Keyboard Settings, which can be run using {{Ic|xfce4-keyboard-settings}}.
  
====Openbox====
+
==== Openbox ====
 +
 
 
You can set keyboard shortcuts and actions in the keyboard section of your {{ic|~/.config/openbox/rc.xml}} file. For example, the following will lower the volume with a media key:
 
You can set keyboard shortcuts and actions in the keyboard section of your {{ic|~/.config/openbox/rc.xml}} file. For example, the following will lower the volume with a media key:
 +
 
  <keybind key="XF86AudioLowerVolume">
 
  <keybind key="XF86AudioLowerVolume">
<action name="Execute">
+
  <action name="Execute">
<execute>amixer set Master 5- unmute</execute>
+
    <execute>amixer set Master 5- unmute</execute>
</action>
+
  </action>
 
  </keybind>
 
  </keybind>
 +
 
For more information, please visit [http://urukrama.wordpress.com/openbox-guide/#Key_mouse urukrama's Openbox Guide] or the [http://openbox.org/wiki/Help:Actions Openbox Wiki].
 
For more information, please visit [http://urukrama.wordpress.com/openbox-guide/#Key_mouse urukrama's Openbox Guide] or the [http://openbox.org/wiki/Help:Actions Openbox Wiki].
  
 
You can use obkey utility from [[AUR]] for easy configuration.
 
You can use obkey utility from [[AUR]] for easy configuration.
  
====PekWM====
+
==== PekWM ====
 +
 
 
Setting keys in PekWM is accomplished by editing your {{ic|~/.pekwm/keys}} file. For example, adding the following at the bottom of the  Global section will lower the volume with a media key:
 
Setting keys in PekWM is accomplished by editing your {{ic|~/.pekwm/keys}} file. For example, adding the following at the bottom of the  Global section will lower the volume with a media key:
 +
 
  KeyPress = "XF86AudioLowerVolume" { Actions = "exec amixer set Master 5%- unmute &" }
 
  KeyPress = "XF86AudioLowerVolume" { Actions = "exec amixer set Master 5%- unmute &" }
  
====Xmonad====
+
==== Xmonad ====
 +
 
 
If you use Xmonad as a stand alone window manager, you can edit the xmonad.hs to add unbound keyboard keys. You just need to find the Xf86 name of the key (such as XF86PowerDown) and look it up in {{Ic|/usr/include/X11/XF86keysym.h}}. It will give you a keycode (like 0x1008FF2A) which you can use to add a line like the following in the keybindings section of your {{ic|xmonad.hs}}:
 
If you use Xmonad as a stand alone window manager, you can edit the xmonad.hs to add unbound keyboard keys. You just need to find the Xf86 name of the key (such as XF86PowerDown) and look it up in {{Ic|/usr/include/X11/XF86keysym.h}}. It will give you a keycode (like 0x1008FF2A) which you can use to add a line like the following in the keybindings section of your {{ic|xmonad.hs}}:
 +
 
  ((0,              0x1008FF2A), spawn "sudo pm-suspend")
 
  ((0,              0x1008FF2A), spawn "sudo pm-suspend")
  
====i3====
+
==== i3 ====
 +
 
 
Open your ~/.i3/config and just bind the key (keysym or keycode) to a command:
 
Open your ~/.i3/config and just bind the key (keysym or keycode) to a command:
 +
 
  bindsym XF86MonBrightnessDown  exec  xbacklight -dec 10
 
  bindsym XF86MonBrightnessDown  exec  xbacklight -dec 10
 
  bindsym Print                  exec  scrot
 
  bindsym Print                  exec  scrot
  
===Using third-party programs===
+
=== Using third-party programs ===
====sxhkd====
+
 
 +
==== sxhkd ====
 +
 
 
A simple X hotkey daemon with a powerful and compact configuration syntax.
 
A simple X hotkey daemon with a powerful and compact configuration syntax.
  
 
Available as {{aur|sxhkd-git}} and {{aur|sxhkd}} in [[AUR]].
 
Available as {{aur|sxhkd-git}} and {{aur|sxhkd}} in [[AUR]].
====keytouch====
+
 
 +
==== keytouch ====
 +
 
 
KeyTouch is a program which allows you to easily configure the extra function keys of your keyboard. This means that you can define, for every individual function key, what to do if it is pressed.
 
KeyTouch is a program which allows you to easily configure the extra function keys of your keyboard. This means that you can define, for every individual function key, what to do if it is pressed.
  
Line 99: Line 128:
  
 
==== actkbd ====
 
==== actkbd ====
 +
 
From [http://users.softlab.ece.ntua.gr/~thkala/projects/actkbd/ actkbd home page]:
 
From [http://users.softlab.ece.ntua.gr/~thkala/projects/actkbd/ actkbd home page]:
 
:'''actkbd''' (available [https://aur.archlinux.org/packages.php?ID=8056 in AUR]) is a simple daemon that binds actions to keyboard events. It recognises key combinations and can handle press, repeat and release events. Currently it only supports the linux-2.6 evdev interface. It uses a plain-text configuration file which contains all the bindings.
 
:'''actkbd''' (available [https://aur.archlinux.org/packages.php?ID=8056 in AUR]) is a simple daemon that binds actions to keyboard events. It recognises key combinations and can handle press, repeat and release events. Currently it only supports the linux-2.6 evdev interface. It uses a plain-text configuration file which contains all the bindings.
Line 104: Line 134:
 
A sample configuration and guide is available [http://users.softlab.ece.ntua.gr/~thkala/projects/actkbd/latest/README here].
 
A sample configuration and guide is available [http://users.softlab.ece.ntua.gr/~thkala/projects/actkbd/latest/README here].
  
====xbindkeys====
+
==== xbindkeys ====
 +
 
 
''[[xbindkeys]]'' (available in the extra repository) allows advanced mapping of keycodes to actions independently of the Desktop Environment.
 
''[[xbindkeys]]'' (available in the extra repository) allows advanced mapping of keycodes to actions independently of the Desktop Environment.
  
 
A GUI called {{aur|xbindkeys_config}} is available in [[AUR]].
 
A GUI called {{aur|xbindkeys_config}} is available in [[AUR]].

Revision as of 18:46, 2 October 2013

Summary help replacing me
A general overview of how to assign actions to extra keyboard keys in Xorg.
Related
Extra Keyboard Keys
Extra Keyboard Keys in Console
Map scancodes to keycodes
Xorg
Xmodmap

When we are in a graphical environment we may want a key to print a special character or execute a command. There are some ways of doing that and they are covered in this HOWTO.

Note: This article assumes that your keys already have keycodes and that you know these codes, if not, see the Extra Keyboard Keys article where it is explained.

Map keycodes to symbols

Introduction

The most traditional and proficient way to make a key output a character when you are in X is to use xmodmap. Xmodmap is roughly the X equivalent of loadkeys: it reads a file containing some directives. As loadkeys, it can be used to modify many aspects of the behaviour of your keyboard (such as modifiers, etc.), but I will not cover these aspects in this article. The only kind of directive I am interested in here associates an X keycode to a keysym. xmodmap is included in the xorg-server-utils package in the Official Repositories.

Step 1: Create the xmodmap file

In this file, you have to list the keycode directives, with the following syntax:

keycode <Xkeycode> = <keysym>

The list of X keysyms can be read in /usr/include/X11/keysymdef.h. Anyway, most of them are intuitive. Let us say that the X keycode of my hotkey is 239. If I want it to output a literal 'e', I will write the following directive:

keycode 239 = e

If I want it to output the symbol of the American currency, I will write the following directive:

keycode 239 = dollar

This can also be used to assign functions to multimedia keys. Special functions can be found in /usr/include/X11/XF86keysym.h.

An example ~/.Xmodmap:

keycode 160 = XF86AudioMute
keycode 176 = XF86AudioRaiseVolume
keycode 174 = XF86AudioLowerVolume

Multimedia programs such as Rhythmbox and Exaile are designed to work with keys assigned to XF86 Symbols out-of-the-box, without the need to configure a third-party application.

Step 2: Testing

Finally I have to source the file with xmodmap:

$ xmodmap ~/.Xmodmap

Step 3: Making it permanent

Obviously, this will work only for the current X session, use xprofile to make it permanent.

Map keycodes to actions

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: keycodes are mapped to keysyms and then keysyms can be mapped to actions (Discuss in Talk:Extra keyboard keys in Xorg#)

There are multiple ways to do that:

  • The most portable way using low level tools, such as acpid. Not all keys are supported, but configuration in uniform way is possible for keyboard keys, power adapter connection and even headphone jack (un)plugging events.
  • The universal way using Xorg utilities (e.g. Xbindkeys) and eventually your desktop environment or window manager tools.
  • The quicker way using a third-party program to do everything in GUI, such as the Gnome Control Center or Keytouch.

Using your Desktop Environment tools

Gnome

Gnome Control Center is quite complete for the extra keyboard keys management. In fact it can directly detect scancodes which means that it can map any key seen by the kernel.

KDE

Keyboard shortcuts can be configured in System Settings -> Shortcuts and Gestures.

Xfce4

You can change the keyboard shortcuts in Keyboard Settings, which can be run using xfce4-keyboard-settings.

Openbox

You can set keyboard shortcuts and actions in the keyboard section of your ~/.config/openbox/rc.xml file. For example, the following will lower the volume with a media key:

<keybind key="XF86AudioLowerVolume">
  <action name="Execute">
    <execute>amixer set Master 5- unmute</execute>
  </action>
</keybind>

For more information, please visit urukrama's Openbox Guide or the Openbox Wiki.

You can use obkey utility from AUR for easy configuration.

PekWM

Setting keys in PekWM is accomplished by editing your ~/.pekwm/keys file. For example, adding the following at the bottom of the Global section will lower the volume with a media key:

KeyPress = "XF86AudioLowerVolume" { Actions = "exec amixer set Master 5%- unmute &" }

Xmonad

If you use Xmonad as a stand alone window manager, you can edit the xmonad.hs to add unbound keyboard keys. You just need to find the Xf86 name of the key (such as XF86PowerDown) and look it up in /usr/include/X11/XF86keysym.h. It will give you a keycode (like 0x1008FF2A) which you can use to add a line like the following in the keybindings section of your xmonad.hs:

((0,               0x1008FF2A), spawn "sudo pm-suspend")

i3

Open your ~/.i3/config and just bind the key (keysym or keycode) to a command:

bindsym XF86MonBrightnessDown  exec  xbacklight -dec 10
bindsym Print                  exec  scrot

Using third-party programs

sxhkd

A simple X hotkey daemon with a powerful and compact configuration syntax.

Available as sxhkd-gitAUR and sxhkdAUR in AUR.

keytouch

KeyTouch is a program which allows you to easily configure the extra function keys of your keyboard. This means that you can define, for every individual function key, what to do if it is pressed.

See the detailed article: keytouch.

actkbd

From actkbd home page:

actkbd (available in AUR) is a simple daemon that binds actions to keyboard events. It recognises key combinations and can handle press, repeat and release events. Currently it only supports the linux-2.6 evdev interface. It uses a plain-text configuration file which contains all the bindings.

A sample configuration and guide is available here.

xbindkeys

xbindkeys (available in the extra repository) allows advanced mapping of keycodes to actions independently of the Desktop Environment.

A GUI called xbindkeys_configAUR is available in AUR.