33SharpHook provides the ability to simulate keyboard and mouse events, as well as text entry, in a cross-platform way as
44well. It provides the ` IEventSimulator ` interface, and the default implementation, ` EventSimulator ` , which calls
55` UioHook.PostEvent ` to simulate the events by default (though it's configurable). The methods in this interface return
6- a ` UioHookResult ` to specify whether the event was simulated successfully, or not.
6+ a ` UioHookResult ` to specify whether the events were simulated successfully or not.
77
88Simulated events can be distinguished from real ones in a global hook handler with the ` HookEventArgs.IsEventSimulated `
99property.
1010
1111## Event Simulation
1212
13+ ### Example
14+
1315Input event simulation is quite straightforward. Here's a quick example:
1416
1517``` csharp
@@ -28,6 +30,9 @@ simulator.SimulateKeyPress(KeyCode.VcC);
2830simulator .SimulateKeyRelease (KeyCode .VcC );
2931simulator .SimulateKeyRelease (KeyCode .VcLeftControl );
3032
33+ // Simulate pressing Ctrl, then pressing C, then releasing C, then releasing Ctrl
34+ simulator .SimulateKeyStroke (KeyCode .VcLeftControl , KeyCode .VcC );
35+
3136// Press the left mouse button
3237simulator .SimulateMousePress (MouseButton .Button1 );
3338
@@ -53,6 +58,8 @@ simulator.SimulateMouseWheel(
5358type : MouseWheelScrollType .UnitScroll ); // UnitScroll by default
5459```
5560
61+ ### Mouse Wheel Simulation
62+
5663Mouse wheel simulation is a little more complex than other events.
5764
5865A positive ` rotation ` value indicates scrolling up or left, and a negative value indicates scrolling down or right.
@@ -65,6 +72,63 @@ scrolling, so `MouseWheelScrollType.BlockScroll` is recommended for line scrolli
6572
6673On Linux, there is no fixed recommendation, but multiples of 100 can be used. The value of ` type ` is ignored.
6774
75+ ### Simulating a Sequence of Events
76+
77+ ` IEventSimulator ` contains the ` Sequence ` method which returns an ` IEventSimulationSequenceBuilder ` . This object can be
78+ used to build a sequence of events that will be simulated together. If contains several methods like ` AddKeyPress ` and
79+ ` AddMouseMovement ` which add specific events to the sequence. It also contains general-purpose methods: ` AddEvent ` and
80+ ` AddEvents ` which can add any event, as well as ` RemoveEvent ` and ` RemoveEvents ` which remove specific events from the
81+ sequence. The events can be simulated using the ` Simulate ` method. For example:
82+
83+ ``` csharp
84+ simulator .Sequence ()
85+ .AddMouseMovementRelative (20 , 20 )
86+ .AddMousePress (MouseButton .Button1 )
87+ .AddMouseRelease (MouseButton .Button1 )
88+ .AddMouseMovementRelative (- 20 , - 20 )
89+ .Simulate ();
90+ ```
91+
92+ Using ` Sequence ` should be preferred to multiple calls to various ` SimulateXXX ` when simulating multiple events. On
93+ Windows, all events will be simulated using a single Windows API call. On macOS and Linux, each event will be simulated
94+ one-by-one, but it's still slightly more efficient than multiple ` PostEvent ` calls as some structures will only be
95+ initialized once for all events. ` IEventSimulationSequenceBuilder.Simulate ` also returns ` UioHookResult ` to indicate
96+ whether it was successful or not. On Windows, either all events are simulated, or none are. On macOS and Linux, if a
97+ failure occurs in the middle of the simulation sequence, then further events will not be simulated.
98+
99+ ` IEventSimulationSequenceBuilder ` also contains the ` CreateTemplate ` method which returns an
100+ ` IEventSimulationSequenceTemplate ` . This object represents an immutable template for simulating a predetermined sequence
101+ of events and contains only a single method - ` Simulate ` . For example:
102+
103+ ``` csharp
104+ var diagonalScrollTemplate = simulator .Sequence ()
105+ .AddMouseWheel (rotation : - 120 , direction : MouseWheelScrollDirection .Vertical )
106+ .AddMouseWheel (rotation : - 120 , direction : MouseWheelScrollDirection .Horizontal )
107+ .CreateTemplate ();
108+
109+ diagonalScrollTemplate .Simulate ();
110+ diagonalScrollTemplate .Simulate ();
111+ diagonalScrollTemplate .Simulate ();
112+ ```
113+
114+ ` IEventSimulationSequenceBuilder ` has the ` AddKeyStroke ` extension method which adds a sequence of key presses and a
115+ reversed sequence of key releases. For example, these two snippets will have equivalent results:
116+
117+ ``` csharp
118+ builder .AddKeyStroke (KeyCode .VcLeftControl , KeyCode .VcC );
119+ ```
120+
121+ ``` csharp
122+ builder
123+ .AddKeyPress (KeyCode .VcLeftControl )
124+ .AddKeyPress (KeyCode .VcC )
125+ .AddKeyRelease (KeyCode .VcC )
126+ .AddKeyRelease (KeyCode .VcLeftControl );
127+ ```
128+
129+ ` IEventSimulator ` has the ` SimulateKeyStroke ` extension method which creates a sequence builder, calls ` AddKeyStroke `
130+ for it, and simulates this sequence of events.
131+
68132## Text Entry Simulation
69133
70134SharpHook also provides text entry simulation. ` IEventSimulator ` contains the ` SimulateTextEntry ` method which accepts
0 commit comments