4
4
5
5
# rdev
6
6
7
- Simple library to listen and send events ** globally** to keyboard and mouse on MacOS , Windows and Linux
7
+ Simple library to listen and send events ** globally** to keyboard and mouse on macOS , Windows and Linux
8
8
(x11).
9
9
10
10
You can also check out [ Enigo] ( https://github.com/Enigo-rs/Enigo ) which is another
11
11
crate which helped me write this one.
12
12
13
- This crate is so far a pet project for me to understand the rust ecosystem.
13
+ This crate is so far a pet project for me to understand the Rust ecosystem.
14
14
15
15
## Listening to global events
16
16
@@ -34,16 +34,16 @@ fn callback(event: Event) {
34
34
### OS Caveats:
35
35
When using the ` listen ` function, the following caveats apply:
36
36
37
- ### Mac OS
37
+ ### macOS
38
38
The process running the blocking ` listen ` function (loop) needs to be the parent process (no fork before).
39
- The process needs to be granted access to the Accessibility API (ie . if you're running your process
39
+ The process needs to be granted access to the Accessibility API (i.e . if you're running your process
40
40
inside Terminal.app, then Terminal.app needs to be added in
41
41
System Preferences > Security & Privacy > Privacy > Accessibility)
42
- If the process is not granted access to the Accessibility API, MacOS will silently ignore rdev's
43
- ` listen ` calleback and will not trigger it with events. No error will be generated.
42
+ If the process is not granted access to the Accessibility API, macOS will silently ignore rdev's
43
+ ` listen ` callback and will not trigger it with events. No error will be generated.
44
44
45
45
### Linux
46
- The ` listen ` function uses X11 APIs, and so will not work in Wayland or in the linux kernel virtual console
46
+ The ` listen ` function uses X11 APIs, and so will not work in Wayland or in the Linux kernel virtual console
47
47
48
48
## Sending some events
49
49
@@ -79,7 +79,7 @@ send(&EventType::Wheel {
79
79
### Event
80
80
81
81
In order to detect what a user types, we need to plug to the OS level management
82
- of keyboard state (modifiers like shift, ctrl , but also dead keys if they exist).
82
+ of keyboard state (modifiers like shift, CTRL , but also dead keys if they exist).
83
83
84
84
` EventType ` corresponds to a * physical* event, corresponding to QWERTY layout
85
85
` Event ` corresponds to an actual event that was received and ` Event.name ` reflects
@@ -97,17 +97,16 @@ pub struct Event {
97
97
```
98
98
99
99
Be careful, Event::name, might be None, but also String::from(""), and might contain
100
- not displayable unicode characters. We send exactly what the OS sends us so do some sanity checking
100
+ not displayable Unicode characters. We send exactly what the OS sends us, so do some sanity checking
101
101
before using it.
102
102
Caveat: Dead keys don't function yet on Linux
103
103
104
104
### EventType
105
105
106
- In order to manage different OS, the current EventType choices is a mix&match
107
- to account for all possible events.
106
+ In order to manage different OS, the current EventType choices is a mix and match to account for all possible events.
108
107
There is a safe mechanism to detect events no matter what, which are the
109
108
Unknown() variant of the enum which will contain some OS specific value.
110
- Also not that not all keys are mapped to an OS code, so simulate might fail if you
109
+ Also, not that not all keys are mapped to an OS code, so simulate might fail if you
111
110
try to send an unmapped key. Sending Unknown() variants will always work (the OS might
112
111
still reject it).
113
112
@@ -155,10 +154,9 @@ We can define a dummy Keyboard, that we will use to detect
155
154
what kind of EventType trigger some String. We get the currently used
156
155
layout for now !
157
156
Caveat : This is layout dependent. If your app needs to support
158
- layout switching don't use this !
157
+ layout switching, don't use this!
159
158
Caveat: On Linux, the dead keys mechanism is not implemented.
160
- Caveat: Only shift and dead keys are implemented, Alt+unicode code on windows
161
- won't work.
159
+ Caveat: Only shift and dead keys are implemented, Alt+Unicode code on Windows won't work.
162
160
163
161
``` rust
164
162
use rdev :: {Keyboard , EventType , Key , KeyboardState };
@@ -172,9 +170,9 @@ let string = keyboard.add(&EventType::KeyPress(Key::KeyS));
172
170
173
171
Installing this library with the ` unstable_grab ` feature adds the ` grab ` function
174
172
which hooks into the global input device event stream.
175
- by suppling this function with a callback, you can intercept
173
+ By supplying this function with a callback, you can intercept
176
174
all keyboard and mouse events before they are delivered to applications / window managers.
177
- In the callback, returning None ignores the event and returning the event let's it pass.
175
+ In the callback, returning None ignores the event and returning the event lets it pass.
178
176
There is no modification of the event possible here (yet).
179
177
180
178
Note: the use of the word ` unstable ` here refers specifically to the fact that the ` grab ` API is unstable and subject to change
@@ -201,23 +199,22 @@ if let Err(error) = grab(callback) {
201
199
### OS Caveats:
202
200
When using the ` listen ` and/or ` grab ` functions, the following caveats apply:
203
201
204
- #### Mac OS
202
+ #### macOS
205
203
The process running the blocking ` grab ` function (loop) needs to be the parent process (no fork before).
206
- The process needs to be granted access to the Accessibility API (ie . if you're running your process
204
+ The process needs to be granted access to the Accessibility API (i.e . if you're running your process
207
205
inside Terminal.app, then Terminal.app needs to be added in
208
206
System Preferences > Security & Privacy > Privacy > Accessibility)
209
207
If the process is not granted access to the Accessibility API, the ` grab ` call will fail with an
210
- EventTapError (at least in MacOS 10.15, possibly other versions as well)
208
+ EventTapError (at least in macOS 10.15, possibly other versions as well)
211
209
212
210
#### Linux
213
211
The ` grab ` function use the ` evdev ` library to intercept events, so they will work with both X11 and Wayland
214
- In order for this to work, the process runnign the ` listen ` or ` grab ` loop needs to either run as root (not recommended),
212
+ In order for this to work, the process running the ` listen ` or ` grab ` loop needs to either run as root (not recommended),
215
213
or run as a user who's a member of the ` input ` group (recommended)
216
214
Note: on some distros, the group name for evdev access is called ` plugdev ` , and on some systems, both groups can exist.
217
215
When in doubt, add your user to both groups if they exist.
218
216
219
217
## Serialization
220
218
221
- Event data returned by the ` listen ` and ` grab ` functions can be serialized and de-serialized with
219
+ Event data returned by the ` listen ` and ` grab ` functions can be serialized and deserialized with
222
220
Serde if you install this library with the ` serialize ` feature.
223
-
0 commit comments