Global Hooks

SharpHook provides the IGlobalHook interface along with two default implementations which you can use to control the hook and subscribe to its events. Here's a basic usage example:

First, you create the hook, then subscribe to its events, and then run it. The Run method runs the hook on the current thread, blocking it. The RunAsync() method runs the hook on a separate thread and returns a Task which is finished when the hook is destroyed. You can subscribe to events after the hook is started.

IGlobalHook extends IDisposable. When you call the Dispose method on a hook, it's destroyed. The contract of the interface is that once a hook has been destroyed, it cannot be started again - you'll have to create a new instance. Calling Dispose when the hook is not running is safe - it just won't do anything (other than marking the instance as disposed).

Hook events are of type HookEvent or a derived type which contains more info. It's possible to suppress event propagation by setting the SuppressEvent property to true inside the event handler. This must be done synchronously and is only supported on Windows and macOS.

Important: Always use one instance of IGlobalHook at a time in the entire application since they all must use the same static method to set the hook callback for libuiohook, so there may only be one callback at a time.

SharpHook provides two implementations of IGlobalHook:

• SharpHook.SimpleGlobalHook runs all of its event handlers on the same thread on which the hook itself runs. This means that the handlers should generally be fast since they will block the hook from handling the events that follow if they run for too long.

• SharpHook.TaskPoolGlobalHook runs all of its event handlers on other threads inside the default thread pool for tasks. The parallelism level of the handlers can be configured. On backpressure it will queue the remaining handlers. This means that the hook will be able to process all events. This implementation should be preferred to SimpleGlobalHook except for very simple use-cases. But it has a downside - suppressing event propagation will be ignored since event handlers are run on other threads.

The library also provides the SharpHook.GlobalHookBase class which you can extend to create your own implementation of the global hook. It calls the appropriate event handlers, and you only need to implement a strategy for dispatching the events. It also contains a finalizer which will stop the global hook if this object is not reachable anymore.

Reactive Global Hooks

Use the SharpHook.Reactive package for reactive global hooks.

Event Simulation

SharpHook provides the ability to simulate keyboard and mouse events in a cross-platform way as well. Here's a quick example:

SharpHook provides the IEventSimulator interface, and the default implementation, EventSimulator, which calls UioHook.PostEvent to simulate the events.

Text Entry Simulation

Starting with version 5.0.0, SharpHook also provides text entry simulation. IEventSimulator contains the SimulateTextEntry method which accepts a string. The text to simulate doesn't depend on the current keyboard layout. The full range of UTF-16 (including surrogate pairs, e.g. emojis) is supported.

Logging

libuiohook can log messages throughout its execution. By default the messages are not logged anywhere, but you can get these logs by using the ILogSource interface and its default implementation, LogSource:

As with global hooks, you should use only one LogSource object at a time. ILogSource extends IDisposable - you can dispose of a log source to stop receiving libuiohook messages. You should keep a reference to an instance of LogSource when you use it since it will stop receiving messages when garbage collector deletes it, to avoid memory leaks.

An EmptyLogSource class is also available - this class doesn't listen to the libuiohook logs and can be used instead of LogSource in release builds.

Testing

SharpHook provides two classes which make testing easier. They aren't required since mocks can be used instead, but unlike mocks, no setup is required to use these classes.

SharpHook.Testing.TestGlobalHook provides an implementation of IGlobalHook and IEventSimulator which can be used for testing. When the Run or RunAsync method is called, it will dispatch events using the various Simulate methods from IEventSimulator.

If this class is used as an IEventSimulator in tested code, then the SimulatedEvents property can be checked to see which events were simulated using the test instance.

If an IReactiveGlobalHook is needed for testing, then ReactiveGlobalHookAdapter can be used to adapt an instance of TestGlobalHook.

If the low-level functionality of SharpHook should be mocked, or mocking should be pushed as far away as possible, then SharpHook.Testing.TestProvider can be used. It implements every interface in the SharpHook.Providers namespace and as such it can be used instead of a normal low-level functionality provider.

Like TestGlobalHook, this class can post events using the PostEvent method and dispatch them if Run was called. It also contains the PostedEvents property.

Icon

Icon made by Freepik from www.flaticon.com.