{"id":19225995,"url":"https://github.com/developer239/robot-cpp","last_synced_at":"2025-04-10T22:42:09.568Z","repository":{"id":157485386,"uuid":"633078660","full_name":"developer239/robot-cpp","owner":"developer239","description":"Mouse, keyboard and display automation.","archived":false,"fork":false,"pushed_at":"2025-03-11T11:55:31.000Z","size":92,"stargazers_count":17,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T19:39:32.184Z","etag":null,"topics":["cmake","control","cpp","keyboard","macos","mouse","record","replay","windows"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/developer239.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-04-26T18:26:52.000Z","updated_at":"2025-03-11T11:55:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"47397cb9-be25-466a-b907-d4d43653373d","html_url":"https://github.com/developer239/robot-cpp","commit_stats":{"total_commits":26,"total_committers":1,"mean_commits":26.0,"dds":0.0,"last_synced_commit":"39779b641c1edc582f5ebcf2ea17af73e91ca2c2"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developer239%2Frobot-cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developer239%2Frobot-cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developer239%2Frobot-cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developer239%2Frobot-cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/developer239","download_url":"https://codeload.github.com/developer239/robot-cpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248312208,"owners_count":21082638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cmake","control","cpp","keyboard","macos","mouse","record","replay","windows"],"created_at":"2024-11-09T15:17:01.484Z","updated_at":"2025-04-10T22:42:09.559Z","avatar_url":"https://github.com/developer239.png","language":"C++","readme":"# Robot CPP\n\n![Build](https://github.com/developer239/robot-cpp/actions/workflows/build.yml/badge.svg)\n[![MacOS Tests](https://github.com/developer239/robot-cpp/actions/workflows/test-macos.yml/badge.svg)](https://github.com/developer239/robot-cpp/actions/workflows/test-macos.yml)\n[![Windows Tests](https://github.com/developer239/robot-cpp/actions/workflows/test-windows.yml/badge.svg)](https://github.com/developer239/robot-cpp/actions/workflows/test-windows.yml)\n\nThis library is inspired by older unmaintained libraries like [octalmage/robotjs](https://github.com/octalmage/robotjs)\nand [Robot/robot-js](https://github.com/Robot/robot-js). The goal is to provide cross-platform controls for various\ndevices such as keyboard, mouse, and screen for C++ applications.\n\n**Supported system:**\n\n- MacOS\n- Windows\n\nIn case of Linux, please, create issue and leave a star and I will implement support. Right now I want to focus on port to\nNode.js using Node-API.\n\n## What can you do with it?\n\n- Move mouse and simulate clicks\n- Simulate keyboard presses and releases as well as easily program more advanced interactions (for example `TypeHumanLike`)\n- Capture selected part of the screen and save it as PNG\n- **Record and replay mouse and keyboard events**\n\nThere are some limitations but I would be more than happy to fix them and implement additional features. Feel free to create issue I will make the PR. 👀\n\n## Installation\n\nAdd this library as submodule:\n\n```git\n$ git submodule add https://github.com/developer239/robot-cpp externals/robot-cpp \n```\n\nLoad modules dependencies:\n```git\n$ git submodule update --init --recursive\n```\n\nUpdate your CMake:\n\n```CMake\nadd_subdirectory(externals/robot-cpp)\ntarget_link_libraries(\u003cyour_target\u003e PRIVATE RobotCPP)\n```\n\n## Types\n\n### Point\n\n`Point` is a structure that represents a 2D point with integer coordinates (x, y). It also provides a method to\ncalculate the distance between two points.\n\n#### Attributes\n\n- `int x;`\n  The x-coordinate of the point.\n\n- `int y;`\n  The y-coordinate of the point.\n\n#### Methods\n\n- `double Distance(Point target) const;`\n  Calculates and returns the Euclidean distance between the current point and the specified `target` point.\n\n### Example Usage\n\n```cpp\n#include \"robot.h\"\n\nint main() {\n  Robot::Point p1{100, 200};\n  Robot::Point p2{300, 400};\n  double distance = p1.Distance(p2);\n  std::cout \u003c\u003c \"Distance between p1 and p2: \" \u003c\u003c distance \u003c\u003c std::endl;\n}\n```\n\n## Mouse Class\n\nThe `Mouse` class provides a static interface for controlling the mouse cursor, simulating mouse clicks, and scrolling.\n\n### Public Methods\n\n- `static void Move(Robot::Point point);`\n  Moves the mouse cursor to the specified point (x, y).\n\n- `static void MoveSmooth(Robot::Point point, double speed = 1500);`\n  Moves the mouse cursor smoothly to the specified point (x, y) at the given speed.\n\n- `static void Drag(Robot::Point point, double speed = 1500);`\n  Drags the mouse cursor to the specified point (x, y) at the given speed.\n\n- `static Robot::Point GetPosition();`\n  Returns the current position of the mouse cursor as a `Robot::Point`.\n\n- `static void ToggleButton(bool down, MouseButton button, bool doubleClick = false);`\n  Presses or releases the specified mouse button depending on the `down` argument. If `doubleClick` is set to true, it\n  will perform a double click.\n\n- `static void Click(MouseButton button);`\n  Simulates a single click using the specified mouse button.\n\n- `static void DoubleClick(MouseButton button);`\n  Simulates a double click using the specified mouse button.\n\n- `static void ScrollBy(int y, int x = 0);`\n  Scrolls the mouse wheel by the specified x and y distances.\n\n### Example Usage\n\n```cpp\n#include \"robot.h\"\n\nint main() {\n  Robot::Mouse::MoveSmooth({100, 200});\n}\n```\n\n## Keyboard Class\n\nThe `Keyboard` class provides a static interface for simulating keyboard key presses, releases, and typing.\n\n### Public Methods\n\n- `static void Type(const std::string\u0026 query);`\n  Types the given text as a string.\n\n- `static void TypeHumanLike(const std::string\u0026 query);`\n  Types the given text as a string with a human-like typing speed.\n\n- `static void Click(char asciiChar);`\n  Simulates a key press and release for the specified ASCII character.\n\n- `static void Click(SpecialKey specialKey);`\n  Simulates a key press and release for the specified special key.\n\n- `static void Press(char asciiChar);`\n  Simulates a key press for the specified ASCII character.\n\n- `static void Press(SpecialKey specialKey);`\n  Simulates a key press for the specified special key.\n\n- `static void Release(char asciiChar);`\n  Simulates a key release for the specified ASCII character.\n\n- `static void Release(SpecialKey specialKey);`\n  Simulates a key release for the specified special key.\n\n### Example Usage\n\n```cpp\n#include \"robot.h\"\n\nint main() {\n  // Note that this will type the text in lower case and likely without special characters like !@#$%^\u0026*()\n  Robot::Keyboard::TypeHumanLike(\"Hello, World\");\n}\n```\n\n## Screen Class\n\nThe `Screen` class provides functionality to capture the screen, get pixel colors, and save the captured screen as a PNG image.\n\n### Public Methods\n\n- `Pixel GetPixelColor(int x, int y);`\n  Returns the color of the pixel at the specified (x, y) coordinates as a `Pixel` structure.\n\n- `DisplaySize GetScreenSize();`\n  Returns the size of the screen as a `DisplaySize` structure containing the width and height.\n\n- `void Capture(int x = 0, int y = 0, int width = -1, int height = -1);`\n  Captures a rectangular area of the screen defined by the specified (x, y) coordinates and dimensions (width, height).\n\n- `std::vector\u003cPixel\u003e GetPixels() const;`\n  Returns a vector of `Pixel` structures representing the captured screen.\n\n- `void SaveAsPNG(const std::string \u0026filename);`\n  Saves the captured screen as a PNG image with the specified filename.\n\n### Structures\n\n#### DisplaySize\n\n`DisplaySize` is a structure that represents the size of a display with integer dimensions (width, height).\n\n##### Attributes\n\n- `int width;`\n  The width of the display.\n\n- `int height;`\n  The height of the display.\n\n#### Pixel\n\n`Pixel` is a structure that represents the color of a pixel with unsigned char values for red, green, and blue channels.\n\n##### Attributes\n\n- `unsigned char r;`\n  The red channel value of the pixel.\n\n- `unsigned char g;`\n  The green channel value of the pixel.\n\n- `unsigned char b;`\n  The blue channel value of the pixel.\n\n### Example Usage\n\n```cpp\n#include \"robot.h\"\n\nint main() {\n  Robot::Screen screen;\n  screen.Capture(0, 0, 800, 600);\n  Robot::Pixel pixel = screen.GetPixelColor(100, 200);\n  screen.SaveAsPNG(\"screenshot.png\");\n}\n```\n\n## Record and Replay Keyboard and Mouse Actions\n\n**Note:** It seems that recorded mouse position is slightly shifted on Windows.\n\nThe `ActionRecorder` and `EventHook` classes provide functionality for recording user actions (such as mouse clicks and keyboard key presses) and replaying them later.\n\n### ActionRecorder Class\n\nThe `ActionRecorder` class is responsible for recording user actions and storing them as a sequence of actions. It provides methods to record mouse clicks, keyboard key presses, and mouse movements.\n\n#### Public Methods\n\n- `void RecordPressLeft(float x, float y);`\n  Records a left mouse button press action at the specified coordinates (x, y).\n\n- `void RecordReleaseLeft(float x, float y);`\n  Records a left mouse button release action at the specified coordinates (x, y).\n\n- `void RecordKeyPress(uint16_t key);`\n  Records a keyboard key press action for the specified virtual key code.\n\n- `void RecordKeyRelease(uint16_t key);`\n  Records a keyboard key release action for the specified virtual key code.\n\n- `void RecordMouseMove(float x, float y);`\n  Records a mouse movement action to the specified coordinates (x, y).\n\n- `void ReplayActions();`\n  Replays the recorded actions in the same sequence they were recorded.\n\n### EventHook Class\n\nThe `EventHook` class is responsible for hooking into system events and capturing user actions in real-time. It uses the Core Graphics Event Tap API to intercept mouse and keyboard events. The captured events are then forwarded to the `ActionRecorder` for recording.\n\n#### Public Methods\n\n- `explicit EventHook(ActionRecorder\u0026 recorder);`\n  Constructs an `EventHook` object with a reference to the `ActionRecorder` instance.\n\n- `void StartRecording();`\n  Starts the event hook and begins recording user actions.\n\n- `void StopRecording();`\n  Stops the event hook and stops recording user actions.\n\nPlease note that the `EventHook` class currently supports macOS, and Windows support is not yet implemented.\n\n### Example Usage\n\nHere's an example code snippet demonstrating how to use the `ActionRecorder` and `EventHook` classes to record and replay user actions:\n\n```cpp\n#include \u003cEventHook.h\u003e\n#include \u003cUtils.h\u003e\n#include \u003ciostream\u003e\n\nint main() {\n  int recordFor = 10;\n\n  Robot::ActionRecorder recorder;\n  Robot::EventHook hook(recorder);\n\n  std::cout \u003c\u003c \"Start recording actions in 3 seconds...\" \u003c\u003c std::endl;\n  std::this_thread::sleep_for(std::chrono::seconds(3));\n\n  // Start recording\n  std::cout \u003c\u003c \"Starting to record actions for \" \u003c\u003c recordFor \u003c\u003c \" seconds...\" \u003c\u003c std::endl;\n  std::thread recordingThread([\u0026hook] { hook.StartRecording(); });\n\n  // Sleep for 10 seconds\n  std::this_thread::sleep_for(std::chrono::seconds(recordFor));\n\n  // Stop recording\n  std::cout \u003c\u003c \"Stopping recording...\" \u003c\u003c std::endl;\n  hook.StopRecording();\n  recordingThread.join();\n\n  // Wait for 5 seconds before replaying\n  std::cout \u003c\u003c \"Replaying actions in 3 seconds...\" \u003c\u003c std::endl;\n  std::this_thread::sleep_for(std::chrono::seconds(3));\n\n  // Replay the recorded actions\n  std::cout \u003c\u003c \"Replaying actions...\" \u003c\u003c std::endl;\n  recorder.ReplayActions();\n\n  return 0;\n}\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeveloper239%2Frobot-cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeveloper239%2Frobot-cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeveloper239%2Frobot-cpp/lists"}