https://github.com/axide-dev/axidev-io
A lightweight C++ library for cross-platform keyboard input injection and monitoring.
https://github.com/axide-dev/axidev-io
cpp io keyboard library linux macos windows
Last synced: 5 days ago
JSON representation
A lightweight C++ library for cross-platform keyboard input injection and monitoring.
- Host: GitHub
- URL: https://github.com/axide-dev/axidev-io
- Owner: axide-dev
- License: mit
- Created: 2025-12-22T19:05:04.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-01-07T10:01:07.000Z (16 days ago)
- Last Synced: 2026-01-13T21:19:50.327Z (9 days ago)
- Topics: cpp, io, keyboard, library, linux, macos, windows
- Language: C++
- Homepage:
- Size: 471 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# axidev-io
A lightweight C++ library for cross-platform keyboard input injection and monitoring.
## Documentation
Documentation is split by audience in the `docs/` directory:
- Consumers: `docs/consumers/README.md` — quickstart, examples, and usage notes.
- Developers: `docs/developers/README.md` — build instructions, architecture notes, testing, and contributing.
Start with the document that matches your goal.
## Quickstart
CMake (consumer) usage:
```cpp
cmake_minimum_required(VERSION 3.15)
find_package(axidev-io CONFIG REQUIRED)
add_executable(myapp src/main.cpp)
target_link_libraries(myapp PRIVATE axidev::io)
```
Minimal usage example:
```cpp
#include
int main() {
using namespace axidev::io::keyboard;
Sender sender;
if (sender.capabilities().canInjectKeys) {
// All operations use KeyWithModifier
sender.tap({Key::A, Modifier::None}); // Tap 'a'
sender.tap({Key::A, Modifier::Shift}); // Tap 'A' (uppercase)
sender.tap({Key::C, Modifier::Ctrl}); // Ctrl+C
// Or parse from string
auto combo = stringToKeyWithModifier("Ctrl+S");
sender.tap(combo);
}
return 0;
}
```
## C API (C wrapper)
A compact C ABI is available for consumers that want to bind axidev-io from other
languages. The C API header is installed as `` and provides
opaque handle types for keyboard `Sender` and `Listener`, simple helpers to convert key
names, and a small set of functions to control keyboard sending and listening from C.
Basic usage (C):
```c
#include
#include
/* Example keyboard listener callback */
static void my_cb(uint32_t codepoint, axidev_io_keyboard_key_with_modifier_t key_mod,
bool pressed, void *ud) {
(void)ud;
(void)codepoint; /* Prioritize key_mod for portability */
char *name = axidev_io_keyboard_key_to_string_with_modifier(key_mod);
printf("key=%s %s\n", name ? name : "?", pressed ? "pressed" : "released");
if (name) axidev_io_free_string(name);
}
int main(void) {
axidev_io_keyboard_sender_t sender = axidev_io_keyboard_sender_create();
if (!sender) {
char *err = axidev_io_get_last_error();
if (err) {
fprintf(stderr, "keyboard sender create: %s\n", err);
axidev_io_free_string(err);
}
return 1;
}
axidev_io_keyboard_capabilities_t caps;
axidev_io_keyboard_sender_get_capabilities(sender, &caps);
if (caps.can_inject_keys) {
/* All operations use axidev_io_keyboard_key_with_modifier_t */
axidev_io_keyboard_key_with_modifier_t key_mod;
/* Tap 'A' key */
axidev_io_keyboard_string_to_key_with_modifier("A", &key_mod);
axidev_io_keyboard_sender_tap(sender, key_mod);
/* Ctrl+C combo */
axidev_io_keyboard_string_to_key_with_modifier("Ctrl+C", &key_mod);
axidev_io_keyboard_sender_tap(sender, key_mod);
} else if (caps.can_inject_text) {
axidev_io_keyboard_sender_type_text_utf8(sender, "Hello from C API\n");
}
axidev_io_keyboard_sender_destroy(sender);
/* Keyboard listener example (may require platform permissions) */
axidev_io_keyboard_listener_t listener = axidev_io_keyboard_listener_create();
if (listener && axidev_io_keyboard_listener_start(listener, my_cb, NULL)) {
/* ... application runs ... */
axidev_io_keyboard_listener_stop(listener);
}
axidev_io_keyboard_listener_destroy(listener);
return 0;
}
```
Notes:
- Strings returned by the C API are heap-allocated and must be freed with
`axidev_io_free_string`.
- Keyboard listener callbacks may be invoked from an internal thread; your callback
must be thread-safe.
- Use `axidev_io_get_last_error()` to retrieve a heap-allocated error message if
a function fails (free it with `axidev_io_free_string`).
An example C program is available at `examples/example_c.c`. Build it with:
```bash
mkdir build
cd build
cmake .. -DAXIDEV_IO_BUILD_EXAMPLES=ON -DCMAKE_BUILD_TYPE=Release
cmake --build .
```
## Building from source
```bash
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
```
## Contributing
- Update `docs/consumers/` or `docs/developers/` for user- or developer-facing changes.
- Add tests or examples to `examples/` where relevant.
- Open a pull request with a clear description and focused changes.
## License
See the `LICENSE` file in the project root.
## Reporting issues
Open issues in the project's issue tracker and include reproduction steps, platform, and any relevant logs or details.