GlobalHotKeys.Latur 1.0.6

GlobalHotKeys

A universal C# library for handling global hotkeys using keyboard and mouse combinations at a low level. Built with modularity, cross-project reuse, and developer ergonomics in mind.

✅ Features

• 📦 Global low-level input hook (keyboard + mouse)
• 🔀 Unified KeyCode enum for keyboard and mouse
• 🧠 Combo logic with support for modifier + button combos (e.g. Ctrl + Shift + XButton1)
• 🔧 Easy registration using Bind and HotkeyCombination
• 🔁 Trigger-once execution until all keys are released
• 🧼 Clean modular architecture (fully self-contained)
• 🪟 Built on Win32 SendInput and SetWindowsHookEx

📂 Project Structure

🚀 Quick Start

dotnet add package GlobalHotKeys.Latur

using GlobalHotKeys;
using GlobalHotKeys.Structs;

var manager = new GlobalHotKeys.HotKeys();

manager.Register(new Bind("screenshot", KeyCode.Control, KeyCode.F5), async () =>
{
    Console.WriteLine("Screenshot triggered!");
});

manager.Start();

🧠 How It Works

1. Low-level hooks are installed using optimized Win32 APIs (no blocking calls)
2. Keys and mouse buttons are unified into a HashSet<KeyCode>
3. When a combination is pressed, it's matched against registered actions
4. The action is only invoked once per full press-release cycle
5. You can dynamically register, update, or remove combos during runtime

⚡ Performance Improvements (v1.0.6+)

• Instant startup: Eliminated blocking Process.MainModule calls
• Optimized hook installation: Uses GetModuleHandle(null) for maximum speed
• Removed unnecessary async overhead: Windows handles callbacks directly
• Better error handling: Proper cleanup on hook installation failures

🔧 Example Usage

Register a Hotkey:

manager.Register(new Bind("open-dev", KeyCode.LControl, KeyCode.LShift, KeyCode.D), async () =>
{
    Console.WriteLine("Dev Tools Opened");
});

Change an Existing Combo:

manager.Change("open-dev", new HotkeyCombination(false, KeyCode.Control, KeyCode.F1));

Remove a Combo:

manager.Unregister("open-dev");

🖥️ Console Applications

Important: Console applications require a Windows message loop to process low-level hooks. Without a message loop, hotkeys will not work even if the hooks are installed successfully.

Solution 1: Using WinForms (Recommended)

Add a reference to System.Windows.Forms and use Application.Run():

using System;
using System.Threading.Tasks;
using System.Windows.Forms; // Add this using
using GlobalHotKeys;
using GlobalHotKeys.Structs;

[STAThread]
public static async Task Main(string[] args)
{
    var hotKeys = new HotKeys();
    hotKeys.Start();

    hotKeys.Register(new Bind("test-hotkey", () => 
    {
        Console.WriteLine("Hotkey triggered!");
        return Task.CompletedTask;
    }, KeyCode.F1, KeyCode.LControl));

    // This runs a proper Windows message loop
    Application.Run();
}

Solution 2: Custom Message Loop (No Dependencies)

If you prefer not to add WinForms dependency, implement a minimal message loop:

using System;
using System.Runtime.InteropServices;
using System.Threading.Tasks;
using GlobalHotKeys;
using GlobalHotKeys.Structs;

[STAThread]
public static async Task Main(string[] args)
{
    var hotKeys = new HotKeys();
    hotKeys.Start();

    hotKeys.Register(new Bind("test-hotkey", () => 
    {
        Console.WriteLine("Hotkey triggered!");
        return Task.CompletedTask;
    }, KeyCode.F1, KeyCode.LControl));

    // Run a minimal message loop
    while (true)
    {
        var msg = new MSG();
        var result = GetMessage(ref msg, IntPtr.Zero, 0, 0);
        
        if (result <= 0) break; // WM_QUIT or error
        
        TranslateMessage(ref msg);
        DispatchMessage(ref msg);
    }
}

// Required P/Invoke declarations
[StructLayout(LayoutKind.Sequential)]
public struct MSG
{
    public IntPtr hwnd;
    public uint message;
    public IntPtr wParam;
    public IntPtr lParam;
    public uint time;
    public POINT pt;
}

[StructLayout(LayoutKind.Sequential)]
public struct POINT
{
    public int x, y;
}

[DllImport("user32.dll")]
static extern int GetMessage(ref MSG lpMsg, IntPtr hWnd, uint wMsgFilterMin, uint wMsgFilterMax);

[DllImport("user32.dll")]
static extern bool TranslateMessage(ref MSG lpMsg);

[DllImport("user32.dll")]
static extern IntPtr DispatchMessage(ref MSG lpMsg);

Why This Is Required

Low-level hooks (WH_KEYBOARD_LL and WH_MOUSE_LL) are processed by Windows through the message queue. Console applications don't have a message loop by default, so:

1. ✅ Hooks install successfully
2. ✅ Windows calls your hook procedures when input occurs
3. ❌ Without a message loop, the thread doesn't process messages
4. ❌ Hotkeys appear to not work

The message loop ensures that Windows can properly deliver hook callbacks to your application.

🔒 Limitations

• Windows-only (relies on SetWindowsHookEx)
• Must run on STA thread for hook reliability
• Cannot detect keys consumed by some protected fullscreen games
• Console applications require a message loop (see Console Apps section below)

🐛 Fixed Issues

• ✅ Startup lag in WinForm applications (especially when debugging)
• ✅ Infinite stutter in Console applications
• ✅ Performance issues with hook installation
• ✅ Resource leaks on hook installation failures

🔧 Troubleshooting

Common Issues

Q: My application still has startup lag after updating A: Make sure you're using the latest version (v1.0.6+). The performance improvements are significant.

Q: Hooks don't work in my Console application A: Console applications require a Windows message loop to process low-level hooks. See the Console Applications section above for complete solutions.

Q: Hotkeys don't trigger in some games A: Some games with anti-cheat systems may block low-level hooks. This is a security feature, not a library issue.

Q: Getting "Failed to install hook" errors A: Ensure your application has sufficient permissions and isn't running in a sandboxed environment.

🧱 Building from Source

git clone https://github.com/latur-h/GlobalHotKeys
cd GlobalHotKeys
dotnet build -c Release

📋 Version History

v1.0.6+ (Latest)

• ⚡ Major Performance Improvements
  • Eliminated startup lag in WinForm and Console applications
  • Replaced blocking Process.MainModule with fast GetModuleHandle(null)
  • Removed unnecessary async task overhead
  • Added robust error handling and cleanup
• 🛡️ Enhanced Reliability
  • Better hook installation error handling
  • Proper resource cleanup on failures
  • Improved thread safety

v1.0.5 and earlier

• Initial release with basic hotkey functionality
• Global keyboard and mouse hook support
• Hotkey combination matching and execution

📜 License

MIT — free for personal and commercial use.