KeyHook provides low level rebinding of both keyboard keys and mouse keys, as well as creation of macros. It is especially useful for both games and applications which do no support rebinding of keys. The bindings are built and run as a normal C++ program.
If you ever wanted to rebind your WASD-keys to your scroll wheel (just to spice things up a bit), look no further!
Basic setup
#include "KeyHook.h"
using namespace kh;
class MyKeyHook : public KeyHook {
protected:
void script() {
// Script code goes here (executed every key press)
}
};
int main() {
MyKeyHook hook;
hook.start();
return EXIT_SUCCESS;
}
Basic usage
Rebind A
to B
.
on(A, B);
Keys can be disabled.
mute(Win);
Modifier keys work as expected and allows greater flexibility.
on(Ctrl + C, Ctrl + V);
on(Ctrl + V, Ctrl + C);
on(Ctrl + Alt + Delete, Ctrl + S);
on(LShift, RShift);
Rebind mouse scrolling
to arrow keys
, and vice versa.
// Rebind mouse scroll
on(MouseScrollDown, ArrowDown);
on(MouseScrollUp, ArrowUp);
on(MouseScrollLeft, ArrowLeft);
on(MouseScrollRight, ArrowRight);
// Rebind arrow keys
on(ArrowDown, MouseScrollDown);
on(ArrowUp, MouseScrollUp);
on(ArrowLeft, MouseScrollLeft);
on(ArrowRight, MouseScrollRight);
Action
-objects can be used for greater customisation. Lambda capture (&
) is required.
on(Ctrl + W, Action([&] {
// Press Ctrl + A
send(Ctrl + A);
// Press Ctrl + A
send(Ctrl, true);
send(A);
send(Ctrl, false);
// Press keys in sequence to spell out text
send("Write this text...");
}));
on
can be nested.
static bool enable = true;
on(Enter, enable); // Toggle boolean
on(enable, Action([&] {
on(A, Action([&] {
// Code...
});
}));
Important: avoid using if
statements in favor of on
in script()
. This ensures that rebound keys are sent and released correctly when a condition is enabled/disabled.
// if
on(condition, Action([&] {
// true
}));
// if/else
on(condition, Action([&] {
// true
}), Action([&] {
// false
}));
Advanced usage
Move steering controls from arrow keys
to WASD
, where Enter
brings up an in game chat window. This is an useful bindings in many strategy games, e.g. Age of Empires, Company of Heroes.
void script() {
static bool enable = true;
// Only apply when specified window is active
on(isWindow("Some strategy game"), Action([&] {
// Disable/Enable bindings when pressing "Enter" without silencing the key,
// which is useful to allow typing when "Enter" brings up the chat window.
// The flag "Send" (passed using the `-` operator) prevents "Enter" from
// being silenced.
on(Enter - Send, enable);
// Disable/Enable bindings when pressing Ctrl + Enter, if you somehow
// need to manually correct.
on(Ctrl + Enter, enable);
on(enable, Action([&] {
// Rebind WASD to arrow keys
on(W, ArrowUp);
on(A, ArrowLeft);
on(S, ArrowDown);
on(D, ArrowRight);
// Allow WASD by Ctrl-clicking
on(Ctrl + W, W);
on(Ctrl + A, A);
on(Ctrl + S, S);
on(Ctrl + D, D);
}));
}));
}
Execute something during regular intervals:
void script() {
// Script code goes here (executed every key press)
}
void init() {
// Do something every 100 millisecond
every(100, [&] {
// Keep sending A if A is pressed
if(isPressed(A)) {
send(A);
}
});
}
Tips
Feel free to experiement with the API. Most of the safe to use public methods are documented with Doxygen-style annotations.
Please note that rebinding of keys are based on scan code. The predefined keys are based on a US keyboard layout. Please consult the following chart to make modifications if unsure:
Only usable on Windows currently, but most of the logic is platform independent and can be compiled under both Linux and Windows. Feel free to help out if you have the time.
KeyHook requires installing the third-party lib Interception.
- Download Interception.zip v.1.0.1
- Install Interception drivers by running
install-interception.exe
as administrator - IMPORTANT: Restart computer for drivers to work
The preferred way of building KeyHook is with Cmake.
CMake gives you multiple options of building the executable.
If you have CMake added to you PATH, and have "Visual Studio 15 2017" or similar installed, here is one way it can be done:
With Git Bash installed you can simply execute the BUILD.sh for a default build. The binaries are found in KeyHook\build\Release
.
You can also perform the steps manually by executing the following commands in almost any terminal:
# From root directory of KeyHook open any terminal and perform the following commands
# For building x86
mkdir build32
cd build32
cmake -G "Visual Studio 15 2017" ..
cmake --build . --config Release
cd ..
# For building x64
mkdir build64
cd build64
cmake -G "Visual Studio 15 2017 Win64" ..
cmake --build . --config Release
- Expose a scripting API using Lua
- Reading and sending of mouse movement
- Screen grabbing/reading
- Support different keyboard layouts
Low level keyboard reading on Windows are handled with Interception by Oblitum. Note: KeyHook was originally based on WinApi LowLevelKeyboardProc, however this method does not work for some games, especially older games based on DirectInput.
Licensed under CC BY 4.0. Third party libraries are licensed under own respective licenses.
See LICENSE.md for more information.