kbd-mangler
Version 2.X
If you happen to know kbd-mangler 0.3 - The version 2.0 and above is something completely different,
Consider it an entirely new program, forget
that previous versions ever existed and read the entire documentation again.
The main highlights of the new architecture are:
- No need to touch kernel
- Write your manglers in JavaScript
- not limited to keyboard, any type of events can be mangled and emited
If you are interested, here is the documentation of the 0.3 version.
NOTE: the old versions and old architecture is no longer maintained, sorry.
An important note for the impatient:
Before you start mangling, memorize the following RESCUE KEY COMBINATION:
RIGHT CONTROL + RIGHT SHIFT.
In case a mangler script "steals" your keyboard this combination terminates the kbd-mangler program.
Table of contents
Introduction
kbd-mangler is a tool to modify the default behaviour of the input devices such as keyboard and mouse
at a low level. Modifications are transparent for the
entire system and work naturally with any console or X application.
kbd-mangler grabs the the given input devices (like /etc/input/event3)
and forwards ALL events to the specified mangler script.
Mangler script does whatever it wants with the events and emits events to the uinput device (/dev/uinput).
The System does not know whether it receives genuine events from your hardware or mangled events from kbd-mangler.
Mangler scripts are written in JavaScript aka ECMA-262.
This project is hosted at SourceForge.net
For latest downloads and other project related information visit the
SourceForge.net project page:
http://sourceforge.net/projects/kbd-mangler/
FAQ
What can I use kbd-mangler for?
You can do anything with input coming from keyboard, mouse, etc before the system gets a chance to interprete these events.
I don't get it, can you give me an example?
I was using kbd-mangler to make that part of the keyboard to the right
from the <Enter> key entirely obsolete. Space key pressed in
combination with some letter keys 'simulates' the arrows and other
'obsolete' physical keys.
Why? I wanted my hands to always stay at the classical blind-typing position and never move away.
check examples/aux_key.js
A few other examples:
examples/abbr.js - configure any number of abbreviations that get expanded automatically in ANY application as you type.
examples/aux_mouse.js - control your mouse pointer with keyboard.
How do I make kbd-mangler work with my console / X application xyz?
The advantage of kbd-mangler and one of the reasons for its existence
is that it works on the level much lower than distinction between
any console or X applications. It modifies the input behaviour at it's
very origin.
Thus ANY program expecting input from keyboard, mouse, etc will be affected
by kbd-mangler without any specific configuration regardless whether it is
a console or an X application.
What systems will kbd-mangler run on?
It will work out of the box on Linux running
stock kernel versions 2.6.x.
What do I need to know to use kbd-mangler?
You must speak JavaScript. There are a few working examples included in the distribution.
They will help you to get started quickly. When you get the idea, only your imagination is a limit.
Why JavaScript? What does this software have to do with web?
I have chosen JavaScript, because I consider it a fairly simple language suitable perfectly for purposes like this, and easy to embed
as a scripting solution.
If JavaScript is hardly associated with web and browsers in your mind - the short answer is: JavaScript is another programming language
that does not necessarily have anything to do with browsers. A lot of software uses JavaScropt/ECMAScropt as a scripting engine. So
does kbd-mangler.
I want no JavaScript, I want C (or any other language).
Sorry, in this case you are on your own. The main.c file is a good knowledge base and starting point to create your manglers in whatever
language you want.
However, before you start, think about a few things:
- If your concern is performance - believe me, unless you need something really weird and heavy, javascript is definitely performant
enough for something like kbd-mangler. With the included examples you'll never notice it with "top".
- If you consider to share your mangler and someone less experienced comes across it,
JS is much simpler to start with and hack around. (Consider this statement limited to the context of writing kbd-mangler logic)
Is it possible to redefine the rescue key combination?
Yes. It's very simple, open main.c, and edit the rescue_keys array. In order to find the key names run examples/trivial.js.
It will print the names of all keys you press, you'll need to add the KEY_ prefix to the key name.
NOTE: For some reason not all key combinations will work. Initially I tried LSHIFT+RSHIFT+LCTRL+RCTRL, but it just does not want to work for some reason,
at least on my installation.
Disclaimer
This software is provided as is without any warranty.
I am not responsible for any damage caused by using this software.
Use it at your own risk ...
Installation
To compile you will need the spidermonkey library and it's development files.
And you will need to update the Makefile and possibly the run.sh script.
Finding spidermonkey may be a bit complicated.
On ubuntu at least before the Karmic Koala release the packages you needed was:
libmozjs-dev
As per this moment (2010-03-17)
Utuntu does not want to install this package without blood,
but thanks to the hint from folks at mediatomb.org project, you can install
xulrunner-dev
package on Karmic. It will provide spidermonkey library, however under somewhat obscure paths.
You need to set the compiler/linker variables at the top of Makefile accordingly, and you may need to set
the correct LD_LIBRARY_PATH in the run.sh script
On other distributions, try to look for a package like 'smjs'.
In any case, kbd-mangler looks for jsapi.h file, whereever it is.
Once you have found the spidermonkey, simply run make.
Adapt the run.sh script. You need to find your input devices and maybe set the LD_LIBRARY_PATH environment variable
Running
The prefered way is to adapt the run.sh script and use it to run kbd-mangler.
(I believe it's a bit annoying to specify your input devices, include paths, etc every time.)
Please follow the instructions in run.sh script and adapt it before running.
Example:
sudo ./run.sh examples/trivial.js
kbd-mangler command understands following options:
-
-I path (similar to gcc's -I option, adds the given path to the list of include paths where the function include() looks for js files.
-
-r device file specifies input device file to read. Multiple -r options may be given to grab events from several input devices.
NOTE: It is highly recomended to add the keyboard device with -r at least during development of your manglers.
Otherwise you won't have the RESCUE KEY COMBINATION at hand!
-
-w device file specifies the uinput device where events are being emited (by the emit() function).
This is a mandatory option unless you want to completely suppress input from the devices specified with -r option. (Which you most likely don't).
JavaScript API
Kbd-mangler provides several native functions to be used in your mangler scripts.
The complete list of functions is presented here:
function process(event)
This function is an exception to the rest. It is NOT a native function. YOU must implement it in EVERY top-level mangler script.
It is the entry point for your manglers.
Once kbd-mangler initializes and reads the main script it looks for this function and calls it for every event that is read from the input devices.
Event parameter will contain a JS object with following properties:
type: event type, (see EV_* constants in keysyms.js)
code: in case of key event contains the key code (see KEY_* constants in keysyms.js)
value: in case of key event: 1- press, 0-release, 2-repeat
IMPORTANT NOTE:
This function must eventually emit (see emit function) some events back to the system otherwise your system
completely stops responding to any input that is grabbed by kbd-mangler!!!
Normally you want to emit back almost all events you receive with an exception of some keys you wish to suppress or process in a different way.
NOTE: event.type may also be EV_TIMER
This is a special event NOT generated by system, but by the kbd_mangler program in regular intervals.
If you are not interested in this type of event, simply ignore it and there is no need to emit it.
If you wonder what is this event good for - take a look at examples/aux_mouse.js
function emit(type, code, value)
With this function input events are emited into the system. Parameters are the same as properties of the event object passed to the process() function.
NOTE: emit() is not only for emission of extra emulated events in addition to the genuine events. kbd-mangler does NOT forward any events, you must explicitely emit()
all events, regardless whether you have mangled them or just passing them through!
function include(file)
includes(and evaluates) the given javascript file. If a relative path is given kbd-mangler tries to find the path by prepending all include paths specified. (see -I option).
This works similar to the -I option to gcc and the #include directive in C.
function exec(command)
Executes the given command using sh -c command and fork/execvp.
Returns the exit code of the command.
With help of this function your mangling is not limited to emiting input events.
function log(message)
Writes a message to standard output with trailing newline appended automatically.
Useful for debugging purposes.
function time()
Returns current time in milliseconds since some point. Do not rely on this point to be unix epoch, etc,
the function should be only used to compare elapsed time between various events, etc.
NOTE: You can also go the standard javascript way:
new Date().getTime()
P.S.
Your contribution of any kind is always welcome.
Should you have any questions and/or suggestions - drop me a line.
It is likely that this project won't get much activity unless there is evidence that anyone uses it and/or needs my help.
It is a working system and I have put together a few examples giving enough idea how to make something cool and usefull out of it.
If you manage to solve some interesting problem with kbd-mangler, please SHARE your scripts! Maybe someone wants the same or a similar thing.
Author
Gena Batyan < gbatyan AT gmx DOT net >