sbplat/macro-api

Cross-platform Macro API for C++.

Macro API

Cross platform Macro API for C++.

Features • Planned Features • Usage • Contributing • License

Features

• Cross platform (only Windows at the moment)
• Easy to use
• Full keyboard and mouse control
• Get keyboard and mouse states
• Open source

Planned Features

• Mac and Linux support
• More examples and documentation
• More control over your keyboard and mouse
• Image searching

Usage

Integrate using CMake:

include(FetchContent)
FetchContent_Declare(
    macro
    GIT_REPOSITORY https://github.com/sbplat/Macro-API.git
    GIT_TAG main  # or whatever tag/commit you want to use
)
FetchContent_MakeAvailable(macro)

include_directories(${macro_SOURCE_DIR}/include)
# Add your source files here (ex. add_executable(${PROJECT_NAME} main.cpp))
target_link_libraries(${PROJECT_NAME} macro)

Then, in your code:

#include <macro/macro.h>  // Namespace: Macro

Refer to the examples and documentation for a more in-depth look at how to use the API.

Contributing

See our Contributing Guidelines.

License

This project is licensed under the BSD 3-Clause License.

Our Amazing Contributors ❤️

Thanks to these amazing people for contributing to this project:

list generated by contrib.rocks

macro-api's Issues

[Example] Keyboard example for the `Up` and `Down` functions

Create an example using the Up and Down keyboard functions and place it in the examples folder.

Function declarations for Up and Down (see include/macro/keyboard.h):

void Down(Key key);
void Up(Key key);

[TODO] Windows Global Mouse Hook

Implement a global mouse hook for Windows. When there is an event, call the corresponding callback from a new thread.

Possible functions to implement:

LRESULT CALLBACK LowLevelMouseProc(int nCode, WPARAM wParam, LPARAM lParam);
void MouseHookProcLoop();

[Feature Request] Create _States class that represents the key and button states

Is your feature request related to a problem? Please describe.
This will be a lot more lightweight than std::map.

Describe the solution you'd like
A wrapper around an int array called _States that will be used instead of std::map for representing the state of keys and buttons.

Describe alternatives you've considered
N/A.

Additional context
N/A.

[Feature Request] Implement GetKeyState

Is your feature request related to a problem? Please describe.
There isn't a direct function to determine if a key is pressed or not.

Describe the solution you'd like
A function called GetKeyState that gets the state of a key. This function should be implemented in src/common/keyboard.cpp.

Describe alternatives you've considered
GetKeyStates returns a map of all the keys and it's a lot of work to just determine the state of a single key.

Additional context
Function declaration (see include/macro/keyboard.h):

KeyState GetKeyState(Key key);

Want to update README.md file

Is your feature request related to a problem? Please describe.
Want to add How to Contribute section and Contributors profiles into README.md file

@sbplat can you assign this to me please?

[TODO] Windows Global Keyboard Hook

Implement a global keyboard hook for Windows. When there is an event, call the corresponding callback from a new thread.

Possible functions to implement:

LRESULT CALLBACK LowLevelKeyboardProc(int nCode, WPARAM wParam, LPARAM lParam);
void KeyboardHookProcLoop();

Linux support

Keyboard

• MapToOSKey
• MapFromOSKey
• MapFromChar
• Down
• Up

Keyboard Events

• KeyboardHookLoop

Mouse

• GetPosition
• MoveAbsolute
• MoveRelative
• Down
• Up
• Scroll

Mouse Events

• MouseHookLoop

Misc

• PreciseSleep

[TODO] Implement GetButtonStates

Track mouse up/down button events from the mouse hook (see src/win32/mouse_events.cpp) using a std::map and return a const reference of the map for GetState.

See #7 and #18 (very similar).

[Example] Mouse example for the `Up` and `Down` functions

Create an example using the Up and Down mouse functions and place it in the examples folder.

Function declarations for Up and Down (see include/macro/mouse.h):

void Down(Button button);
void Up(Button button);

[Feature Request] Implement GetButtonState

Is your feature request related to a problem? Please describe.
There isn't a direct function to determine if a button is pressed or not.

Describe the solution you'd like
A function called GetButtonState that gets the state of a button. This function should be implemented in src/common/mouse.cpp.

Describe alternatives you've considered
GetButtonStates returns a map of all the buttons and it's a lot of work to just determine the state of a single button.

Additional context
Function declaration (see include/macro/mouse.h):

ButtonState GetButtonState(Button button);

macOS support

Keyboard

• MapToOSKey
• MapFromOSKey
• MapFromChar
• Down
• Up

Keyboard Events

• KeyboardHookLoop

Mouse

• GetPosition
• MoveAbsolute
• MoveRelative
• Down
• Up
• Scroll

Mouse Events

• MouseHookLoop

Misc

• PreciseSleep

Windows support

Keyboard

• MapToOSKey
• MapFromOSKey
• MapFromChar
• Down
• Up

Keyboard Events

• KeyboardHookLoop

Mouse

• GetPosition
• MoveAbsolute
• MoveRelative
• Down
• Up
• Scroll

Mouse Events

• MouseHookLoop

Misc

• PreciseSleep

[Bug] Position from GetPosition and MoveCallback are different on Windows 10

Describe the bug
The position returned from Macro::Mouse::GetPosition is different from the MoveCallback position parameter (callback set using Macro::Mouse::SetMoveCallback).

This bug is caused by DPI scaling. The position returned from GetPosition is scaled to the current DPI, while the position parameter in the MoveCallback is not.

To Reproduce
To reproduce, run the following code on a Windows system with a DPI of 100% or greater and move the mouse around.

#include <macro/macro.h>

#include <iostream>

bool moveCallback(Macro::Mouse::Point moveCallbackPosition) {
    Macro::Mouse::Point getPositionPosition = Macro::Mouse::GetPosition();
    std::cout << "MoveCallback: " << moveCallbackPosition.x << ", " << moveCallbackPosition.y
              << "\n"
              << "GetPosition:  " << getPositionPosition.x << ", " << getPositionPosition.y
              << "\n---" << std::endl;

    return false;
}

int main() {
    Macro::Mouse::SetMoveCallback(moveCallback);
    Macro::Mouse::MouseHookLoop();

    return 0;
}

Output (clipped):

MoveCallback: 867, 732
GetPosition:  694, 587
---
MoveCallback: 864, 731
GetPosition:  694, 586
---
MoveCallback: 863, 731
GetPosition:  691, 585
---
MoveCallback: 862, 730
GetPosition:  690, 585
---

This was run in a Windows 10 environment with a DPI 125%. As shown in the output, the position reported by MoveCallback is 125% of the position reported by GetPosition.

Expected behavior
The position from GetPosition and MoveCallback should be the exact same.

Screenshots/Videos
N/A

Environment

• Platform: win32
• OS: Windows 10
• Compiler: GCC 11.2.0
• Macro API version: 1.0.0 (latest)

Additional context
N/A

[Documentation] Create documentation base

Create a documentation base and document some code that will serve as an example for future documentations.

[Bug] Mouse::MoveAbsolute different on win32 and x11

Describe the bug
The MoveAbsolute function parameters are different on win32 and x11. Calling the function on win32 and x11 will yield completely different results.

• On win32, the range is from (0, 0) to (65535, 65535).
• On x11, the range is from (0, 0) to (screen_x, screen_y).

To Reproduce
The following snippet will move the cursor to the center of the screen on x11 and top left corner on win32.

MoveAbsolute(screen_x / 2, screen_y / 2);

Expected behavior
The cursor should move to the center of the screen on all platforms.

[TODO] CMake tests

Implement unit testing features in CMake.

[Example] Keyboard example for the `Tap` function

Create an example using the Tap keyboard function and place it in the examples folder.

Function declarations for Tap (see include/macro/keyboard.h):

void Tap(Key key);

[Documentation] Add documentation to header files

Keyboard

• Key (enum) #67
• Combo (struct) #63
• GetKeyName #54
• MapToOSKey #56
• MapFromOSKey #56
• MapFromChar #58
• KeyState (enum) #59
• KeyStates (typedef) #62
• KeyCallback (typedef) #65
• SetCallback #65
• KeyboardHookLoop #66
• GetKeyState #68
• GetKeyStates #68
• Down #70
• Up #70
• Tap #71
• Type #72

Mouse

• Button (enum)
• GetButtonName #54
• ButtonState (enum) #59
• Point (struct) #64
• ButtonStates (typedef) #62
• MoveCallback (typedef)
• ButtonCallback (typedef)
• ScrollCallback (typedef)
• SetMoveCallback
• SetButtonCallback
• SetScrollCallback
• MouseHookLoop
• GetPosition
• GetButtonState
• GetButtonStates
• MoveAbsolute
• MoveRelative
• Down
• Up
• Click
• Scroll

Misc

• Sleep #34
• PreciseSleep #34

States

• States (class)

[Tests] Add more unit tests

Current unit tests

Keyboard

• MapToOSKey
• MapFromOSKey
• MapFromChar
• Down
• Up

Keyboard Events

• KeyboardHookLoop

Mouse

• GetPosition
• MoveAbsolute
• MoveRelative
• Down
• Up
• Scroll

Mouse Events

• MouseHookLoop

Misc

• PreciseSleep

[TODO] Implement GetKeyStates

Track key up/down events from the keyboard hook (see src/win32/keyboard_events.cpp) using a std::map and return a const reference of the map for GetState.