Skip to content

Commit c540d34

Browse files
NarsilNarsil
committed
Moving to cargo-readme. (Oh god yes !).
1 parent 858152d commit c540d34

File tree

3 files changed

+153
-100
lines changed

3 files changed

+153
-100
lines changed

‎README.md

+70-92
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,24 @@
22
[![Crate](https://img.shields.io/crates/v/rdev.svg)](https://crates.io/crates/rdev)
33
[![API](https://docs.rs/rdev/badge.svg)](https://docs.rs/rdev)
44

5-
Simple library to listen and send events to keyboard and mouse.
5+
# rdev
6+
7+
Simple library to listen and send events to keyboard and mouse on MacOS, Windows and Linux
8+
(x11).
69

710
You can also check out [Enigo](https://github.com/Enigo-rs/Enigo) which is another
811
crate which helped me write this one.
912

1013
This crate is so far a pet project for me to understand the rust ecosystem.
1114

12-
## Simple Usage
13-
14-
### Listening to global events
15+
## Listening to global events
1516

1617
```rust
1718
use rdev::{listen, Event};
1819

19-
fn main() {
20-
// This will block.
21-
if let Err(error) = listen(callback) {
22-
println!("Error: {:?}", error)
23-
}
20+
// This will block.
21+
if let Err(error) = listen(callback) {
22+
println!("Error: {:?}", error)
2423
}
2524

2625
fn callback(event: Event) {
@@ -32,7 +31,7 @@ fn callback(event: Event) {
3231
}
3332
```
3433

35-
### Sending some events
34+
## Sending some events
3635

3736
```rust
3837
use rdev::{simulate, Button, EventType, Key, SimulateError};
@@ -50,95 +49,31 @@ fn send(event_type: &EventType) {
5049
thread::sleep(delay);
5150
}
5251

53-
fn main() {
54-
send(&EventType::KeyPress(Key::KeyS));
55-
send(&EventType::KeyRelease(Key::KeyS));
56-
57-
send(&EventType::MouseMove { x: 0.0, y: 0.0 });
58-
send(&EventType::MouseMove { x: 400.0, y: 400.0 });
59-
send(&EventType::ButtonPress(Button::Left));
60-
send(&EventType::ButtonRelease(Button::Right));
61-
send(&EventType::Wheel {
62-
delta_x: 0,
63-
delta_y: 1,
64-
});
65-
}
66-
```
67-
68-
### Getting the main screen size
69-
70-
```rust
71-
use rdev::{display_size};
72-
73-
fn main() {
74-
let (w, h) = display_size();
75-
assert!(w > 0);
76-
assert!(h > 0);
77-
}
78-
```
79-
80-
### Keyboard state
81-
82-
We can define a dummy Keyboard, that we will use to detect
83-
what kind of EventType trigger some String. We get the currently used
84-
layout for now !
85-
Caveat : This is layout dependent. If your app needs to support
86-
layout switching don't use this !
87-
Caveat: On Linux, the dead keys mechanism is not implemented.
88-
Caveat: Only shift and dead keys are implemented, Alt+unicode code on windows
89-
won't work.
90-
91-
```rust
92-
use rdev::{Keyboard, EventType, Key, KeyboardState};
93-
94-
let mut keyboard = Keyboard::new().unwrap();
95-
let string = keyboard.add(&EventType::KeyPress(Key::KeyS));
96-
// string == Some("s")
52+
send(&EventType::KeyPress(Key::KeyS));
53+
send(&EventType::KeyRelease(Key::KeyS));
54+
55+
send(&EventType::MouseMove { x: 0.0, y: 0.0 });
56+
send(&EventType::MouseMove { x: 400.0, y: 400.0 });
57+
send(&EventType::ButtonPress(Button::Left));
58+
send(&EventType::ButtonRelease(Button::Right));
59+
send(&EventType::Wheel {
60+
delta_x: 0,
61+
delta_y: 1,
62+
});
9763
```
98-
99-
### Grabbing global events.
100-
101-
In the callback, returning None ignores the event
102-
and returning the event let's it pass. There is no modification of the event
103-
possible here.
104-
Caveat: On MacOS, you require the grab
105-
loop needs to be the primary app (no fork before) and need to have accessibility
106-
settings enabled.
107-
On Linux, this is not implemented, you will always receive an error.
108-
109-
```rust
110-
use rdev::{grab, Event, EventType, Key};
111-
112-
fn callback(event: Event) -> Option<Event> {
113-
println!("My callback {:?}", event);
114-
match event.event_type{
115-
EventType::KeyPress(Key::Tab) => None,
116-
_ => Some(event),
117-
}
118-
}
119-
fn main(){
120-
// This will block.
121-
if let Err(error) = grab(callback) {
122-
println!("Error: {:?}", error)
123-
}
124-
}
125-
```
126-
127-
### Serialization
128-
129-
Serialization and deserialization is optional behind the feature "serialize".
130-
131-
### Event struct
64+
## Main structs
65+
### Event
13266

13367
In order to detect what a user types, we need to plug to the OS level management
13468
of keyboard state (modifiers like shift, ctrl, but also dead keys if they exist).
13569

136-
In order to see what is the outcome of an event, you need to read the Event::name option.
70+
`EventType` corresponds to a *physical* event, corresponding to QWERTY layout
71+
`Event` corresponds to an actual event that was received and `Event.name` reflects
72+
what key was interpreted by the OS at that time, it will respect the layout.
13773

13874
```rust
13975
/// When events arrive from the system we can add some information
140-
/// time is when the event was received, name *will* be at some point changed
141-
/// to be mapped to the function of the key (Alt, s, Return and so on).
76+
/// time is when the event was received.
14277
#[derive(Debug)]
14378
pub struct Event {
14479
pub time: SystemTime,
@@ -152,7 +87,7 @@ not displayable unicode characters. We send exactly what the OS sends us so do s
15287
before using it.
15388
Caveat: Dead keys don't function yet on Linux
15489

155-
### Events enum
90+
### EventType
15691

15792
In order to manage different OS, the current EventType choices is a mix&match
15893
to account for all possible events.
@@ -194,3 +129,46 @@ pub enum EventType {
194129
For now the code only works for Linux (X11), MacOS and Windows. On MacOS, the listen
195130
loop needs to be the primary app (no fork before) and needs to have accessibility
196131
settings enabled (Terminal added in System Preferences > Security & Privacy > Privacy > Accessibility).
132+
133+
## Getting the main screen size
134+
135+
```rust
136+
use rdev::{display_size};
137+
138+
let (w, h) = display_size().unwrap();
139+
assert!(w > 0);
140+
assert!(h > 0);
141+
```
142+
143+
## Keyboard state
144+
145+
We can define a dummy Keyboard, that we will use to detect
146+
what kind of EventType trigger some String. We get the currently used
147+
layout for now !
148+
Caveat : This is layout dependent. If your app needs to support
149+
layout switching don't use this !
150+
Caveat: On Linux, the dead keys mechanism is not implemented.
151+
Caveat: Only shift and dead keys are implemented, Alt+unicode code on windows
152+
won't work.
153+
154+
```rust
155+
use rdev::{Keyboard, EventType, Key, KeyboardState};
156+
157+
let mut keyboard = Keyboard::new().unwrap();
158+
let string = keyboard.add(&EventType::KeyPress(Key::KeyS));
159+
// string == Some("s")
160+
```
161+
162+
## Grabbing global events. (Requires `unstable_grab` feature)
163+
164+
In the callback, returning None ignores the event
165+
and returning the event let's it pass. There is no modification of the event
166+
possible here.
167+
Caveat: On MacOS, you require the grab
168+
loop needs to be the primary app (no fork before) and need to have accessibility
169+
settings enabled.
170+
**Not implemented on Linux, you will always receive an error.**
171+
172+
## Serialization
173+
174+
Serialization and deserialization. (Requires `serialize` feature).

‎README.tpl

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
![](https://github.com/Narsil/rdev/workflows/build/badge.svg)
2+
[![Crate](https://img.shields.io/crates/v/rdev.svg)](https://crates.io/crates/rdev)
3+
[![API](https://docs.rs/rdev/badge.svg)](https://docs.rs/rdev)
4+
5+
# {{crate}}
6+
7+
{{readme}}
8+

‎src/lib.rs

+75-8
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,7 @@
66
//!
77
//! This crate is so far a pet project for me to understand the rust ecosystem.
88
//!
9-
//! ## Simple Usage
10-
//!
11-
//! ### Listening to global events
9+
//! # Listening to global events
1210
//!
1311
//! ```no_run
1412
//! use rdev::{listen, Event};
@@ -27,7 +25,7 @@
2725
//! }
2826
//! ```
2927
//!
30-
//! ### Sending some events
28+
//! # Sending some events
3129
//!
3230
//! ```no_run
3331
//! use rdev::{simulate, Button, EventType, Key, SimulateError};
@@ -57,7 +55,76 @@
5755
//! delta_y: 1,
5856
//! });
5957
//! ```
60-
//! ### Getting the main screen size
58+
//! # Main structs
59+
//! ## Event
60+
//!
61+
//! In order to detect what a user types, we need to plug to the OS level management
62+
//! of keyboard state (modifiers like shift, ctrl, but also dead keys if they exist).
63+
//!
64+
//! `EventType` corresponds to a *physical* event, corresponding to QWERTY layout
65+
//! `Event` corresponds to an actual event that was received and `Event.name` reflects
66+
//! what key was interpreted by the OS at that time, it will respect the layout.
67+
//!
68+
//! ```rust
69+
//! /// When events arrive from the system we can add some information
70+
//! /// time is when the event was received.
71+
//! #[derive(Debug)]
72+
//! pub struct Event {
73+
//! pub time: SystemTime,
74+
//! pub name: Option<String>,
75+
//! pub event_type: EventType,
76+
//! }
77+
//! ```
78+
//!
79+
//! Be careful, Event::name, might be None, but also String::from(""), and might contain
80+
//! not displayable unicode characters. We send exactly what the OS sends us so do some sanity checking
81+
//! before using it.
82+
//! Caveat: Dead keys don't function yet on Linux
83+
//!
84+
//! ## EventType
85+
//!
86+
//! In order to manage different OS, the current EventType choices is a mix&match
87+
//! to account for all possible events.
88+
//! There is a safe mechanism to detect events no matter what, which are the
89+
//! Unknown() variant of the enum which will contain some OS specific value.
90+
//! Also not that not all keys are mapped to an OS code, so simulate might fail if you
91+
//! try to send an unmapped key. Sending Unknown() variants will always work (the OS might
92+
//! still reject it).
93+
//!
94+
//! ```rust
95+
//! /// In order to manage different OS, the current EventType choices is a mix&match
96+
//! /// to account for all possible events.
97+
//! #[derive(Debug)]
98+
//! pub enum EventType {
99+
//! /// The keys correspond to a standard qwerty layout, they don't correspond
100+
//! /// To the actual letter a user would use, that requires some layout logic to be added.
101+
//! KeyPress(Key),
102+
//! KeyRelease(Key),
103+
//! /// Some mouse will have more than 3 buttons, these are not defined, and different OS will
104+
//! /// give different Unknown code.
105+
//! ButtonPress(Button),
106+
//! ButtonRelease(Button),
107+
//! /// Values in pixels
108+
//! MouseMove {
109+
//! x: f64,
110+
//! y: f64,
111+
//! },
112+
//! /// Note: On Linux, there is no actual delta the actual values are ignored for delta_x
113+
//! /// and we only look at the sign of delta_y to simulate wheelup or wheeldown.
114+
//! Wheel {
115+
//! delta_x: i64,
116+
//! delta_y: i64,
117+
//! },
118+
//! }
119+
//! ```
120+
//!
121+
//! ## OS Specificities
122+
//!
123+
//! For now the code only works for Linux (X11), MacOS and Windows. On MacOS, the listen
124+
//! loop needs to be the primary app (no fork before) and needs to have accessibility
125+
//! settings enabled (Terminal added in System Preferences > Security & Privacy > Privacy > Accessibility).
126+
//!
127+
//! # Getting the main screen size
61128
//!
62129
//! ```no_run
63130
//! use rdev::{display_size};
@@ -67,7 +134,7 @@
67134
//! assert!(h > 0);
68135
//! ```
69136
//!
70-
//! ### Keyboard state
137+
//! # Keyboard state
71138
//!
72139
//! We can define a dummy Keyboard, that we will use to detect
73140
//! what kind of EventType trigger some String. We get the currently used
@@ -86,7 +153,7 @@
86153
//! // string == Some("s")
87154
//! ```
88155
//!
89-
//! ### Grabbing global events. (Requires `unstable_grab` feature)
156+
//! # Grabbing global events. (Requires `unstable_grab` feature)
90157
//!
91158
//! In the callback, returning None ignores the event
92159
//! and returning the event let's it pass. There is no modification of the event
@@ -96,7 +163,7 @@
96163
//! settings enabled.
97164
//! **Not implemented on Linux, you will always receive an error.**
98165
//!
99-
//! ### Serialization
166+
//! # Serialization
100167
//!
101168
//! Serialization and deserialization. (Requires `serialize` feature).
102169
mod rdev;

0 commit comments

Comments
 (0)