EventHook 3.0.0-beta

EventHook

Code Quality

A .NET library to subscribe to global user actions across Windows, macOS, and Linux: keyboard, mouse, clipboard, application windows, print jobs, and hotkeys.

• API Documentation (DocFX site on develop)

Install

dotnet add package EventHook

Windows applications must target net10.0-windows. The portable net10.0 package is for macOS and Linux.

Sample

using System;

using (var eventHookFactory = new EventHookFactory())
{
    var keyboardWatcher = eventHookFactory.GetKeyboardWatcher();
    var kb = keyboardWatcher.Start();
    if (!kb.Success)
    {
        Console.WriteLine(kb); // PermissionDenied / PrivilegeRequired / etc.
    }
    else
    {
        keyboardWatcher.OnKeyInput += (s, e) =>
            Console.WriteLine($"Key {e.KeyData.EventType} of {e.KeyData.Keyname}");
    }

    var mouseWatcher = eventHookFactory.GetMouseWatcher();
    mouseWatcher.IncludeMouseMove = false; // default is false
    mouseWatcher.Start().ThrowIfFailed();
    mouseWatcher.OnMouseInput += (s, e) =>
        Console.WriteLine($"Mouse {e.Message} at {e.Point.x},{e.Point.y}");

    var clipboardWatcher = eventHookFactory.GetClipboardWatcher();
    clipboardWatcher.Start().ThrowIfFailed();
    clipboardWatcher.OnClipboardModified += (s, e) =>
        Console.WriteLine($"Clipboard {e.DataFormat}: {e.Data}");

    var applicationWatcher = eventHookFactory.GetApplicationWatcher();
    applicationWatcher.Start().ThrowIfFailed();
    applicationWatcher.OnApplicationWindowChange += (s, e) =>
        Console.WriteLine($"{e.ApplicationData.AppName} was {e.Event}");

    var printWatcher = eventHookFactory.GetPrintWatcher();
    printWatcher.Start().ThrowIfFailed();
    printWatcher.OnPrintEvent += (s, e) =>
        Console.WriteLine($"Printer {e.EventData.PrinterName} pages={e.EventData.Pages}");

    var hotkeyWatcher = eventHookFactory.GetHotkeyWatcher();
    hotkeyWatcher.Start().ThrowIfFailed();
    hotkeyWatcher.Register("demo", new Hotkey(KeyModifiers.Control | KeyModifiers.Alt, EventKey.H))
        .ThrowIfFailed();
    hotkeyWatcher.OnHotkeyPressed += (s, e) =>
        Console.WriteLine($"Hotkey {e.Id} ({e.Hotkey})");

    Console.ReadLine();
}

OS hook callbacks only copy a lightweight snapshot and return immediately. Decoding and user event handlers run on a dedicated offload path so input is never blocked.

Permissions and failures

Start() / Register() return HookStartResult. Check Success, or call ThrowIfFailed(). IsRunning is true only after a successful install.

See examples/MAC.md and examples/LINUX.md for host setup.

Application window filter (Windows)

EventHook.Helpers.AppWindowFilter.IncludeWindowsWithoutSysMenu = true;
EventHook.Helpers.AppWindowFilter.IncludeDialogs = true;
EventHook.Helpers.AppWindowFilter.CustomFilter = hwnd => true;

Hosted apps (COM / Office add-ins on Windows)

Prefer constructing the factory on an STA UI thread, or pass an existing message-pump HWND:

using var factory = new EventHookFactory(hostMainWindowHandle);

Development

• .NET 10 SDK
• Windows: dotnet build src/Event.Hook.sln -c Release
• Portable (macOS/Linux CI): build the library, tests, and console example projects (not the full Windows-only solution)
• dotnet test tests/Event.Hook.Tests
• dotnet test tests/Event.Hook.IntegrationTests
• dotnet test tests/Event.Hook.E2ETests --filter Category=E2E
• Docs: dotnet tool restore then docfx .github/docfx.json

Release branches

Publishing uses NuGet Trusted Publishing (NUGET_USER on the nuget-publish environment).

Version 3.0 notes

Breaking: multi-platform (net10.0-windows + net10.0), Start()/Register() return HookStartResult, portable Hotkey replaces WinForms Keys, IncludeMouseMove defaults to false, non-blocking OS hook offload.

Repository renamed from windows-user-action-hook to event-hook. Solution/projects use Event.Hook.*; NuGet package id remains EventHook.