keytouch-editor - helps to create create keyboard files for keyTouch 2.1

keytouch-editor /dev/input/eventX output-file

keytouch-editor --acpi output-file

1 Introduction

Of course it may be possible that your keyboard is not supported yet by keyTouch. However by using keyTouch editor 2.1 you can get your keyboard supported. This document describes how to use keytouch editor. Unlike keyTouch editor 1, which produces keyboard files for keyTouch 1, keyTouch editor 2.1 does not have a graphical userinterface but a commandline userinterface.

1.1 Who should read this document

If you only want to create a keyboard file for keyTouch 2.1, you are reading the right document now. If you are also interested in the document format of a keyboard file, you should read "How to get your keyboard supported in keyTouch 2.1".

2 Running keyTouch editor

2.1 ACPI hotkeys

Some notebooks have ACPI hotkeys, which are not really part of your keyboard (although it may look like they are). ACPI hotkeys are supported by keyTouch since version 2.1. If your notebook has such keys, you will have run keyTouch editor like this:

$ keytouch-editor --acpi output-file

2.2 Normal keyboards

If you have "normal" extra function keys you will have to read this subsection to start keyTouch editor. You need to be root to run keyTouch editor. So start your favorite terminal program and type:

$ su

(do not type the $ character) Fill in the root password and press enter to load the module. If you are using Ubuntu (or another sudo based distribution) you will have to run:

$ sudo bash

Before starting keyTouch editor, the evdev module has to be loaded. So run (do not type the # character):

# modprobe evdev

If you get a message like

FATAL: Module evdev not found.

the evdev module will probably be included with your kernel.

When you now look in the directory /dev/input/ you will notice that there are some files (devices) called "eventX" (where X is replaced by a number). To see the contents of /dev/input run:

# ls /dev/input

Every event device (like a keyboard or a mouse) is related to one of these files. To find out which file belongs to your keyboard, run:

# keytouch-editor /dev/input/eventX output-file

Replace the X by a number. KeyTouch editor will first show some information about the device, including its name ("Input device name") that can tell you if you have chosen the correct event device. KeyTouch editor asks you to press one of the extra function keys. If the program continues after pressing the extra function key, you have chosen the right event device. If not terminate the program by pressing Ctrl+C and try another event device.

Note that when your keyboard is connected via USB there are two event devices: /dev/input/eventA (where A is replaced by a number) for all "normal" keys and /dev/input/eventB (where B = A+1) for the extra function keys.

3 Filling in general information

After you have found the correct device, keytouch-editor asks your name and the name of the manufacturer and model of your keyboard.

4 The extra function keys

Now it is time to tell keytouch-editor about your extra function keys. You will see the following message:

Press an extra function key or press enter to finish...

If your keyboard is connected via USB or you started keyTouch editor with the "--acpi" option, you will not see this message, but instead:

Press return to a new key or enter F followed by return to finish...

First you will have to press the extra function key so that the program knows which key you mean. It is important that you do not press any other key than the extra function key. After pressing the key you will be asked to enter the keys name, keycode and default action. This will be discussed in the following paragraphs.

When you entered the information, the program asks again to press an extra function key. If there are no more extra function keys, just press enter to write the output file and terminate the program.

4.1 Key name

Choose an appropriate name for the key. Is there for example a text label on the key, use the label as the key's name.

4.2 Keycode

Use one of the keycodes listed below. It actually doesn't matter which keycode you choose. However it is recommended that you choose a keycode that matches the best the function of the key. A keycode may only be used once in a keyboard file.

AGAIN EJECTCLOSECD MAIL REFRESH

ALTERASE EMAIL MEDIA REWIND

BACK EXIT MENU RIGHTMETA

BASSBOOST FASTFORWARD MOVE SCROLLDOWN

BOOKMARKS FILE MSDOS SCROLLUP

BRIGHTNESSDOWN FINANCE MUTE SEARCH

BRIGHTNESSUP FIND NEXTSONG SENDFILE

CALC FORWARD OPEN SETUP

CAMERA FRONT PASTE SHOP

CANCEL HANGUEL PAUSE SLEEP

CHAT HANJA PAUSECD SOUND

CLOSE HELP PHONE SPORT

CLOSECD HOMEPAGE PLAY STOP

COFFEE HP PLAYCD STOPCD

COMPOSE ISO PLAYPAUSE SUSPEND

COMPUTER KBDILLUMDOWN POWER SWITCHVIDEOMODE

CONFIG KBDILLUMTOGGLE PREVIOUSSONG UNDO

CONNECT KBDILLUMUP PRINT VOLUMEDOWN

COPY KPCOMMA PROG1 VOLUMEUP

CUT KPEQUAL PROG2 WAKEUP

CYCLEWINDOWS KPLEFTPAREN PROG3 WWW

DELETEFILE KPPLUSMINUS PROG4 XFER

DIRECTION KPRIGHTPAREN PROPS YEN

EDIT LEFTMETA QUESTION

EJECTCD MACRO RECORD

4.3 Default action

It is important to realize that the default action for a key, is not the action you want to use for this key, but one that corresponds to the function of the key.

The default action can be a program or a plugin. If it is a program, just fill in the name of the program. If it is a plugin type "plugin" (without the quotes) instead. Then fill in the name of the plugin. To get a list of all available plugins, run keyTouch and go to the "Preferences" part. Select the plugin and click the "Information..." button to get a list of the functions of the selected plugin. After entering the plugins name in keytouch-editor, fill in the function name. Note that the name and function you fill in are case sensitive.

5 When finished

When your keyboard file is finished you can import it in keyTouch. It is also very important that your keyboard file is available for other people, so that they do not need to create a keyboard file. I should be most grateful to you if you send the keyboard file to

marvinr@users.sourceforge.net .

This manual page and keytouch-editor were written by Marvin Raaijmakers.