Hotkey Manager API

A lightweight C++ hotkey manager for Windows that allows applications to register global keyboard shortcuts, listen for key presses on a background thread, and trigger callbacks on hotkey press.

Features

• Register global hotkeys using human-readable key combinations
• Listen for hotkey presses on a dedicated background thread
• Thread-safe hotkey event handling

Basic Usage

#include <keyboard.h>
#include <iostream>

int main()
{
    Keyboard& keyboard = Keyboard::instance();
    
    keyboard.registerHotkey("ctrl-alt-c", [](){
        std::cout << "pressed hotkey\n";
    });

    keyboard.wait("esc");
}

or if you want to run the listener on a background thread

#include <keyboard.h>
#include <iostream>

int main()
{
    Keyboard& keyboard = Keyboard::instance();

    keyboard.registerHotkey("ctrl-alt-c", [](){
        std::cout << "hotkey pressed" << std::endl;
    });

    keyboard.runAsync("esc");

    std::this_thread::sleep_for(std::chrono::seconds(5));

    // This join blocks the main thread and keeps waiting for hotkey presses until stop() is called (through pressing "esc" in this case)
    keyboard.join();

    // Use this to stop listening and then rejoin the thread immediately.
    // keyboard.stop()
    // keyboard.join()

    // Alternatively, the destructor also calls stop(); and join();
}

The hotkey parser accept a variety of formats. Here are some examples to demonstrate:

// ctrl-alt-a
keyboard.registerHotkey("ctrl-alt-a", []{printf("1\n");});

// left alt-b
keyboard.registerHotkey("lalt-b", []{printf("2\n");});

//windows-ctrl-c
keyboard.registerHotkey("meta-control-c", []{printf("3\n");});

//windows-right shift-d
keyboard.registerHotkey("windows-rshift-d", []{printf("4\n");});

//alt-left windows-e
keyboard.registerHotkey("alt-lsuper-e", []{printf("5\n");});

//windows-shift-f
keyboard.registerHotkey("cmd-shift-f", []{printf("6\n");});

//alt-g
keyboard.registerHotkey("option-g", []{printf("7\n");});

//windows-h
keyboard.registerHotkey("command-h", []{printf("8\n");});

Including

Option 1 (cmake subdirectory):

git clone https://github.com/andrewmenden/keyboard-cpp.git

and in your CMakeLists.txt use add_subdirectory(keyboard-cpp) and then link with libkeyboard target_link_libraries(${PROJECT_NAME} PRIVATE libkeyboard).

Option 2 (manual include):

git clone https://github.com/andrewmenden/keyboard-cpp.git

then add keyboard-cpp/keyboard.cpp to your project and include the keyboard-cpp directory. In cmake, this is

SET(SOURCES
  keyboard-cpp/keyboard.cpp
  ...
)

add_executable(${PROJECT_NAME} ${SOURCES})

target_include_directories(${PROJECT_NAME} keyboard-cpp)

Option 3 (fetch content)

In cmake use

include(FetchContent)

FetchContent_Declare(
  libkeyboard
  GIT_REPOSITORY https://github.com/andrewmenden/keyboard-cpp.git
  GIT_TAG main # or another tag
)

FetchContent_MakeAvailable(libkeyboard)

target_link_libraries(${PROJECT_NAME} libkeyboard)

TODO

• Add: Helper functions for miscellaneous use such as parseHotkey->hotkey, normalizeHotkey->string, keyToScanCode->int, and isModifier->bool
• Enhance: Allow for an optional suppress: bool argument to be provided to registerHotkey.
• Enhance: Allow for hotkeys to use "+" or "-" instead of only working with "-"

Low priority:

• Add: Functionality for onPress and onRelease.
• Add: Chord listening like ("ctrl-k ctrl-j")
• Add: Macro recording/playing functionality through startRecording, stopRecording, and play. This would also come with press and release methods.
• Add: Documentation
• Enhance: Make this cross platform. (Currently only works on Windows)