event-hook

EventHook

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

Platform	Target framework
Windows	net10.0-windows
macOS / Linux	net10.0

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.

Reason	Typical cause
PermissionDenied	macOS Input Monitoring / Accessibility (TCC)
PrivilegeRequired	Linux /dev/input not readable (add user to input group)
DisplayUnavailable	No DISPLAY / session when required (Linux/macOS). Not used for a missing Win32 pump.
NotSupportedOnPlatform	Feature needs X11 on Linux Wayland-only, or wrong TFM on Windows
AlreadyInUse	Hotkey already registered by another process
NativeFailure	Native API failed after permissions were OK

If EventHookFactory cannot start its own Windows message pump (or macOS cannot start its CFRunLoop), construction throws TimeoutException. That is not a HookStartResult — there is no HookFailureReason for “pump missing.”

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

Message pump / event loop

Hooks need an OS event loop. Callers usually do not create one: the factory (Windows) or platform hosts (macOS / Linux) start it.

Platform	Who pumps	What you must do
Windows	EventHookFactory	Nothing in console/service code. Construct the factory on an STA UI thread or let it create a background STA WinForms loop (EventHook.MessagePump).
macOS	Library CFRunLoop (EventHook.Mac.CFRunLoop)	Nothing. The HWND argument is ignored.
Linux X11	Library XNextEvent thread	Need DISPLAY (or Xvfb). HWND is ignored.
Linux evdev	/dev/input reads (no X loop)	User must be in the input group. Clipboard / windows / hotkeys still need X11.

Windows details

• Keyboard and mouse (WH_KEYBOARD_LL / WH_MOUSE_LL) are installed on the factory pump thread. That thread must keep pumping or Windows stops delivering.
• Clipboard (WM_CLIPBOARDUPDATE), hotkeys (WM_HOTKEY), and application/shell hooks are HWND messages on the same pump.
• WindowHookEx does not use the factory pump. Call Start() from a thread that already pumps messages (your UI thread).
• Hosted COM / Office add-ins: construct the factory on the STA UI thread, or pass that window’s HWND. A provided HWND must keep pumping. EventHook registers hotkeys on that handle but does not subclass it — if you pass a host HWND, your WndProc must dispatch WM_HOTKEY or the watcher will report IsRunning and still never fire.
• Prefer the default new EventHookFactory() (library-owned pump) unless you are hosting and will forward messages.

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

Branch	NuGet	Notes
develop	(no publish)	CI on Windows + macOS + Linux; SonarCloud + DocFX on develop push only
beta	{VersionPrefix}-beta.2	Same CI, then publish prerelease (3.0.0-beta already shipped)
stable / tag v*	{VersionPrefix}	Same CI, then stable release + GitHub Pages docs

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.

Code quality