Update the docs for version 7.0.0

Author: TolikPylypchuk

CHANGELOG.md

@@ -1,5 +1,39 @@
 # SharpHook Changelog
 
+## [v7.0.0](https://github.com/TolikPylypchuk/SharpHook/releases/tag/v7.0.0) (August 10, 2025)
+
+### Breaking Changes
+
+- `SimpleReactiveGlobalHook` was renamed to `ReactiveGlobalHook`.
+
+- The `Run`, `RunAsync`, and `Stop` methods were moved from `IGlobalHook` and `IReactiveGlobalHook` into
+`IBasicGlobalHook` which both `IGlobalHook` and `IReactiveGlobalHook` now extend.
+
+- Because of the previous change, `RunAsync` for reactive global hooks now returns a `Task` instead of an
+`IObservable<Unit>`.
+
+- `ReactiveLogSourceAdapter` now contains a single constructor with a default parameter instead of two constructors.
+
+### New Features
+
+- SharpHook.R3 – a new package for integration with R3 was added.
+
+- `EventLoopGlobalHook` – a new implementation of `IGlobalHook` – was added.
+
+- `IBasicGlobalHook` and `BasicGlobalHookBase` were added for easier creation of custom global hooks with different
+event forms.
+
+- `ReactiveLogSourceAdapter` now implements `ILogSource` in addition to `IReactiveLogSource`.
+
+### Bug Fixes
+
+- On Windows, global hooks now correctly report the key that was pressed or released on non-QWERTY layouts.
+
+### Other Changes
+
+- libuiohook was updated to commit
+[a2cba5f](https://github.com/TolikPylypchuk/libuiohook/tree/a2cba5f125072dad8683e812027a561e598c7a37).
+
 ## [v6.2.0](https://github.com/TolikPylypchuk/SharpHook/releases/tag/v6.2.0) (July 19, 2025)
 
 - The ability to disable events of type `KeyTyped` was added.

README.md

@@ -105,7 +105,8 @@ called.
 
 > [!IMPORTANT]
 > You have to remember that only one global hook can exist at a time since calling `SetDispatchProc` will override the
-> previously set one.
+> previously set one. Also, running a global hook when another global hook is already running will corrupt the internal
+> global state of libuiohook.
 
 Additionally, `UioHook` contains the `PostEvent` method for simulating input events.
 
@@ -117,15 +118,15 @@ libuiohook also provides functions to get various system properties. The corresp
 
 ### Global Hooks
 
-SharpHook provides the `IGlobalHook` interface along with two default implementations which you can use to control the
+SharpHook provides the `IGlobalHook` interface along with three default implementations which you can use to control the
 hook and subscribe to its events. Here's a basic usage example:
 
 ```c#
 using SharpHook;
 
 // ...
 
-var hook = new TaskPoolGlobalHook();
+var hook = new EventLoopGlobalHook();
 
 hook.HookEnabled += OnHookEnabled;     // EventHandler<HookEventArgs>
 hook.HookDisabled += OnHookDisabled;   // EventHandler<HookEventArgs>
@@ -173,25 +174,37 @@ a real difference only on Windows where there are two different global hooks –
 macOS and Linux, there is one hook for all events, and this simply enables filtering keyboard or mouse events out on
 these OSes.
 
-SharpHook provides two implementations of `IGlobalHook`:
+SharpHook provides three 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.EventLoopGlobalHook` runs all of its event handlers on a separate dedicated thread. On backpressure it will
+queue the remaining events which 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 another thread.
+
 - `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.
+tasks. The parallelism level of the handlers can be configured. On backpressure it will queue the remaining events which
+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. In general, `EventLoopGlobalHook` should be preferred instead, as this class provides
+benefits only if events should be processed in parallel, which is rarely the case.
 
 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 keeps a reference to a running global hook so that it's not garbage-collected.
 
+The library also provides the `IBasicGlobalHook` interface and the `BasicGlobalHookBase` class. This class can be
+extended to create a custom global hook which has a different form of events from that in `IGlobalHook`.
+
 ### Reactive Global Hooks
 
-If you're using Rx.NET, you can use the SharpHook.Reactive package to integrate SharpHook with Rx.NET.
+#### Rx.NET
+
+If you're using [Rx.NET](https://github.com/dotnet/reactive), you can use the SharpHook.Reactive package to integrate
+SharpHook with Rx.NET.
 
 SharpHook.Reactive provides the `SharpHook.Reactive.IReactiveGlobalHook` interface along with a default implementation
 which you can use to use to control the hook and subscribe to its observables. Here's a basic example:
@@ -201,7 +214,7 @@ using SharpHook.Reactive;
 
 // ...
 
-var hook = new SimpleReactiveGlobalHook();
+var hook = new ReactiveGlobalHook();
 
 hook.HookEnabled.Subscribe(OnHookEnabled);
 hook.HookDisabled.Subscribe(OnHookDisabled);
@@ -226,20 +239,72 @@ hook.MouseWheel.Subscribe(OnMouseWheel);
 
 hook.Run();
 // or
-hook.RunAsync().Subscribe();
+await hook.RunAsync();
 ```
 
 Reactive global hooks are basically the same as the default global hooks and the same rules apply to them.
 
 SharpHook.Reactive provides two implementations of `IReactiveGlobalHook`:
 
-- `SharpHook.Reactive.SimpleReactiveGlobalHook`. Since we're dealing with observables, it's up to you to decide when
-and where to handle the events through schedulers. A default scheduler can be specified for all observables.
+- `SharpHook.Reactive.ReactiveGlobalHook`. Since we're dealing with observables, it's up to you to decide when and where
+to handle the events through schedulers. A default scheduler can be specified for all observables.
 
 - `SharpHook.Reactive.ReactiveGlobalHookAdapter` adapts an `IGlobalHook` to `IReactiveGlobalHook`. All
 subscriptions and changes are propagated to the adapted hook. There is no default adapter from `IReactiveGlobalHook`
 to `IGlobalHook`. A default scheduler can be specified for all observables.
 
+#### R3
+
+If you're using [R3](https://github.com/Cysharp/R3), you can use the SharpHook.R3 package to integrate SharpHook with
+R3.
+
+SharpHook.R3 provides the `SharpHook.R3.IR3GlobalHook` interface along with a default implementation which you can use
+to use to control the hook and subscribe to its observables. Here's a basic example:
+
+```c#
+using SharpHook.R3;
+
+// ...
+
+var hook = new R3GlobalHook();
+
+hook.HookEnabled.Subscribe(OnHookEnabled);
+hook.HookDisabled.Subscribe(OnHookDisabled);
+
+hook.KeyTyped.Subscribe(OnKeyTyped);
+hook.KeyPressed.Subscribe(OnKeyPressed);
+hook.KeyReleased.Subscribe(OnKeyReleased);
+
+hook.MouseClicked.Subscribe(OnMouseClicked);
+hook.MousePressed.Subscribe(OnMousePressed);
+hook.MouseReleased.Subscribe(OnMouseReleased);
+
+hook.MouseMoved
+    .Debouce(TimeSpan.FromSeconds(0.5))
+    .Subscribe(OnMouseMoved);
+
+hook.MouseDragged
+    .Debouce(TimeSpan.FromSeconds(0.5))
+    .Subscribe(OnMouseDragged);
+
+hook.MouseWheel.Subscribe(OnMouseWheel);
+
+hook.Run();
+// or
+await hook.RunAsync();
+```
+
+R3 global hooks are basically the same as the default global hooks and the same rules apply to them.
+
+SharpHook.R3 provides two implementations of `IR3GlobalHook`:
+
+- `SharpHook.R3.R3GlobalHook`. Since we're dealing with observables, it's up to you to decide when and where to handle
+the events through time providers. A default time provider can be specified for all observables.
+
+- `SharpHook.R3.R3GlobalHookAdapter` adapts an `IGlobalHook` to `IR3GlobalHook`. All subscriptions and changes are
+propagated to the adapted hook. There is no default adapter from `IR3GlobalHook` to `IGlobalHook`. A default time
+provider can be specified for all observables.
+
 ### Event Simulation
 
 SharpHook provides the ability to simulate keyboard and mouse events in a cross-platform way as well. Here's a quick
@@ -286,8 +351,8 @@ simulator.SimulateMouseWheel(
     type: MouseWheelScrollType.UnitScroll); // UnitScroll by default
 ```
 
-SharpHook provides the `IEventSimulator` interface, and the default implementation, `EventSimulator`, which calls
-`UioHook.PostEvent` to simulate the events.
+SharpHook provides the `IEventSimulator` interface, and the default implementation, `EventSimulator`, which by default
+calls `UioHook.PostEvent` to simulate the events.
 
 ### Text Entry Simulation
 
@@ -332,6 +397,19 @@ var reactiveLogSource = new ReactiveLogSourceAdapter(logSource);
 reactiveLogSource.MessageLogged.Subscribe(this.OnMessageLogged);
 ```
 
+SharpHook.R3 contains the `IR3LogSource` and `R3LogSourceAdapter` so you can use them in a more reactive way as well:
+
+```C#
+using SharpHook.Logging;
+using SharpHook.R3.Logging;
+
+// ...
+
+var logSource = LogSource.RegisterOrGet(minLevel: LogLevel.Info);
+var reactiveLogSource = new R3LogSourceAdapter(logSource);
+reactiveLogSource.MessageLogged.Subscribe(this.OnMessageLogged);
+```
+
 ### Testing
 
 SharpHook provides two classes which make testing easier. They aren't required since mocks can be used instead, but
@@ -347,6 +425,9 @@ 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 an `IR3GlobalHook` is needed for testing, then `R3GlobalHookAdapter` 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.
@@ -402,7 +483,7 @@ Place the binaries into the appropriate directories in the `SharpHook` project,
   </tr>
 </table>
 
-With libuiohook in place you can build SharpHook using your usual methods, e.g. with Visual Studio or the `dotnet` CLI.
+With libuiohook in place, you can build SharpHook using your usual methods, e.g. with Visual Studio or the `dotnet` CLI.
 You need .NET 9 to build SharpHook.
 
 ## Icon

SharpHook.slnx

@@ -14,6 +14,7 @@
   </Folder>
   <Folder Name="/Docs/Articles/">
     <File Path="docs/articles/about.md" />
+    <File Path="docs/articles/custom.md" />
     <File Path="docs/articles/hooks.md" />
     <File Path="docs/articles/keycodes.md" />
     <File Path="docs/articles/logging.md" />

SharpHook/Providers/UioHookProvider.cs

@@ -134,7 +134,7 @@ public UioHookResult Run() =>
     /// <returns>The result of the operation.</returns>
     /// <remarks>
     /// This method makes a difference only on Windows where there are two different global hooks – a keyboard hook and
-    /// a mouse hook. On macOS and Linux there is one hook for all events, and this method simply filters mouse events
+    /// a mouse hook. On macOS and Linux, there is one hook for all events, and this method simply filters mouse events
     /// out at the libuiohook level on these OSes.
     /// </remarks>
     public UioHookResult RunKeyboard() =>
@@ -146,7 +146,7 @@ public UioHookResult RunKeyboard() =>
     /// <returns>The result of the operation.</returns>
     /// <remarks>
     /// This method makes a difference only on Windows where there are two different global hooks – a keyboard hook and
-    /// a mouse hook. On macOS and Linux there is one hook for all events, and this method simply filters keyboard
+    /// a mouse hook. On macOS and Linux, there is one hook for all events, and this method simply filters keyboard
     /// events out at the libuiohook level on these OSes.
     /// </remarks>
     public UioHookResult RunMouse() =>
@@ -247,10 +247,10 @@ public UioHookResult PostEvent(ref UioHookEvent e) =>
     /// surrogate pairs, e.g. emojis) is supported.
     /// </para>
     /// <para>
-    /// On Windows text simulation should work correctly and consistently.
+    /// On Windows, text simulation should work correctly and consistently.
     /// </para>
     /// <para>
-    /// On macOS applications are not required to process text simulation, but most of them should handle it correctly.
+    /// On macOS, applications are not required to process text simulation, but most of them should handle it correctly.
     /// </para>
     /// <para>
     /// X11 doesn't support text simulation directly. Instead, for each character, an unused key code is remapped to

SharpHook/README.md

@@ -111,9 +111,10 @@ will be ignored since event handlers are run on another thread.
 
 - `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 events which
-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.
+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. In general, `EventLoopGlobalHook` should be preferred instead, as this class provides
+benefits only if events should be processed in parallel, which is rarely the case.
 
 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
@@ -173,8 +174,8 @@ simulator.SimulateMouseWheel(
     type: MouseWheelScrollType.UnitScroll); // UnitScroll by default
 ```
 
-SharpHook provides the `IEventSimulator` interface, and the default implementation, `EventSimulator`, which calls
-`UioHook.PostEvent` to simulate the events.
+SharpHook provides the `IEventSimulator` interface, and the default implementation, `EventSimulator`, which by default
+calls `UioHook.PostEvent` to simulate the events.
 
 ### Text Entry Simulation
 

SharpHook/SharpHook.xml

@@ -50,11 +50,45 @@ Place the binaries into the appropriate directories in the `SharpHook` project,
   </tr>
 </table>
 
-With libuiohook in place you can build SharpHook using your usual methods, e.g. with Visual Studio or the `dotnet` CLI.
+With libuiohook in place, you can build SharpHook using your usual methods, e.g. with Visual Studio or the `dotnet` CLI.
 You need .NET 9 to build SharpHook.
 
 ## Changelog
 
+### [v7.0.0](https://github.com/TolikPylypchuk/SharpHook/releases/tag/v7.0.0) (August 10, 2025)
+
+#### Breaking Changes
+
+- `SimpleReactiveGlobalHook` was renamed to `ReactiveGlobalHook`.
+
+- The `Run`, `RunAsync`, and `Stop` methods were moved from `IGlobalHook` and `IReactiveGlobalHook` into
+`IBasicGlobalHook` which both `IGlobalHook` and `IReactiveGlobalHook` now extend.
+
+- Because of the previous change, `RunAsync` for reactive global hooks now returns a `Task` instead of an
+`IObservable<Unit>`.
+
+- `ReactiveLogSourceAdapter` now contains a single constructor with a default parameter instead of two constructors.
+
+#### New Features
+
+- SharpHook.R3 – a new package for integration with R3 was added.
+
+- `EventLoopGlobalHook` – a new implementation of `IGlobalHook` – was added.
+
+- `IBasicGlobalHook` and `BasicGlobalHookBase` were added for easier creation of custom global hooks with different
+event forms.
+
+- `ReactiveLogSourceAdapter` now implements `ILogSource` in addition to `IReactiveLogSource`.
+
+#### Bug Fixes
+
+- On Windows, global hooks now correctly report the key that was pressed or released on non-QWERTY layouts.
+
+#### Other Changes
+
+- libuiohook was updated to commit
+[a2cba5f](https://github.com/TolikPylypchuk/libuiohook/tree/a2cba5f125072dad8683e812027a561e598c7a37).
+
 ### [v6.2.0](https://github.com/TolikPylypchuk/SharpHook/releases/tag/v6.2.0) (July 19, 2025)
 
 - The ability to disable events of type `KeyTyped` was added.