Crate evdev [−] [src]
Linux event device handling.
The Linux kernel's "evdev" subsystem exposes input devices to userspace in a generic, consistent way. I'll try to explain the device model as completely as possible. The upstream kernel documentation is split across two files:
- https://www.kernel.org/doc/Documentation/input/event-codes.txt
- https://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt
Devices can expose a few different kinds of events, specified by the Types bitflag. Each
event type (except for RELATIVE and SYNCHRONIZATION) also has some associated state. See the documentation for
Types on what each type corresponds to.
This state can be queried. For example, the DeviceState::led_vals field will tell you which
LEDs are currently lit on the device. This state is not automatically synchronized with the
kernel. However, as the application reads events, this state will be updated if the event is
newer than the state timestamp (maintained internally). Additionally, you can call
Device::sync_state to explicitly synchronize with the kernel state.
As the state changes, the kernel will write events into a ring buffer. The application can read from this ring buffer, thus retrieving events. However, if the ring buffer becomes full, the kernel will drop every event in the ring buffer and leave an event telling userspace that it did so. At this point, if the application were using the events it received to update its internal idea of what state the hardware device is in, it will be wrong: it is missing some events. This library tries to ease that pain, but it is best-effort. Events can never be recovered once lost. For example, if a switch is toggled twice, there will be two switch events in the buffer. However if the kernel needs to drop events, when the device goes to synchronize state with the kernel, only one (or zero, if the switch is in the same state as it was before the sync) switch events will be emulated.
It is recommended that you dedicate a thread to processing input events, or use epoll with the
fd returned by Device::fd to process events when they are ready.
Reexports
pub use Key::*; |
pub use FFEffect::*; |
pub use Synchronization::*; |
Modules
| raw |
Structs
| AbsoluteAxis | |
| Device | |
| DeviceState | |
| Events | |
| FFStatus | |
| Led |
LEDs specified by USB HID. |
| Misc |
Various miscellaneous event types. Current as of kernel 4.1. |
| Props |
Device properties. |
| RawEvents | |
| RelativeAxis | |
| Repeat | |
| Sound | |
| Switch | |
| Types |
Event types supported by the device. |
Enums
| FFEffect | |
| Key |
Scancodes for key presses. |
| Synchronization |
Constants
| ABSOLUTE |
Movement on an absolute axis. Used for things such as touch events and joysticks. |
| ABS_BRAKE | |
| ABS_DISTANCE | |
| ABS_GAS | |
| ABS_HAT0X | |
| ABS_HAT0Y | |
| ABS_HAT1X | |
| ABS_HAT1Y | |
| ABS_HAT2X | |
| ABS_HAT2Y | |
| ABS_HAT3X | |
| ABS_HAT3Y | |
| ABS_MISC | |
| ABS_MT_BLOB_ID |
"Group a set of packets as a blob" |
| ABS_MT_DISTANCE |
"Contact over distance" |
| ABS_MT_ORIENTATION |
"Ellipse orientation" |
| ABS_MT_POSITION_X |
"Center X touch position" |
| ABS_MT_POSITION_Y |
"Center Y touch position" |
| ABS_MT_PRESSURE |
"Pressure on contact area" |
| ABS_MT_SLOT |
"MT slot being modified" |
| ABS_MT_TOOL_TYPE |
"Type of touching device" |
| ABS_MT_TOOL_X |
"Center X tool position" |
| ABS_MT_TOOL_Y |
"Center Y tool position" |
| ABS_MT_TOUCH_MAJOR |
"Major axis of touching ellipse" |
| ABS_MT_TOUCH_MINOR |
"Minor axis (omit if circular)" |
| ABS_MT_TRACKING_ID |
"Unique ID of the initiated contact" |
| ABS_MT_WIDTH_MAJOR |
"Major axis of approaching ellipse" |
| ABS_MT_WIDTH_MINOR |
"Minor axis (omit if circular)" |
| ABS_PRESSURE | |
| ABS_RUDDER | |
| ABS_RX | |
| ABS_RY | |
| ABS_RZ | |
| ABS_THROTTLE | |
| ABS_TILT_X | |
| ABS_TILT_Y | |
| ABS_TOOL_WIDTH | |
| ABS_VOLUME | |
| ABS_WHEEL | |
| ABS_X | |
| ABS_Y | |
| ABS_Z | |
| ACCELEROMETER |
Has an accelerometer. Probably reports relative events in that case? |
| BUTTONPAD |
"has button(s) under pad", according to the header. |
| DIRECT |
"direct input devices", according to the header. |
| FF_STATUS_PLAYING | |
| FF_STATUS_STOPPED | |
| FORCEFEEDBACK |
I believe there are no events of this type, but rather this is used to represent that the device can create haptic effects. |
| FORCEFEEDBACKSTATUS |
A force feedback effect's state changed. |
| KEY |
A key changed state. A key, or button, is usually a momentary switch (in the circuit sense). It has two states: down, or up. There are events for when keys are pressed (become down) and released (become up). There are also "key repeats", where multiple events are sent while a key is down. |
| LED |
An LED was toggled. |
| LED_CAPSL | |
| LED_CHARGING |
"External power connected" |
| LED_COMPOSE | |
| LED_KANA | |
| LED_MAIL |
"Message waiting" |
| LED_MAX | |
| LED_MISC |
"Generic indicator" |
| LED_MUTE | |
| LED_NUML | |
| LED_SCROLLL | |
| LED_SLEEP |
"Stand-by" |
| LED_SUSPEND | |
| MISC |
Miscellaneous events that don't fall into other categories. I'm not quite sure when these happen or what they correspond to. |
| MSC_GESTURE |
Completely unused. |
| MSC_MAX | |
| MSC_PULSELED |
Only used by the PowerMate driver, right now. |
| MSC_RAW |
"Raw" event, rarely used. |
| MSC_SCAN |
Key scancode |
| MSC_SERIAL |
Serial number, only exported for tablets ("Transducer Serial Number") |
| MSC_TIMESTAMP |
Completely unused. |
| POINTER |
This input device needs a pointer ("cursor") for the user to know its state. |
| POINTING_STICK |
Is a pointing stick ("clit mouse" etc, https://xkcd.com/243/) |
| POWER |
I think this is unused? |
| RELATIVE |
Movement on a relative axis. There is no absolute coordinate frame, just the fact that there was a change of a certain amount of units. Used for things like mouse movement or scroll wheels. |
| REL_DIAL | |
| REL_HWHEEL | |
| REL_MISC | |
| REL_RX | |
| REL_RY | |
| REL_RZ | |
| REL_WHEEL | |
| REL_X | |
| REL_Y | |
| REL_Z | |
| REPEAT |
There are no events of this type, to my knowledge, but represents metadata about key repeat configuration. |
| REP_DELAY | |
| REP_PERIOD | |
| SEMI_MT |
Touch rectangle only (I think this means that if there are multiple touches, then the bounding rectangle of all the touches is returned, not each touch). |
| SND_BELL | |
| SND_CLICK | |
| SND_TONE | |
| SOUND |
A sound was made. |
| SWITCH |
Change in a switch value. Switches are boolean conditions and usually correspond to a toggle switch of some kind in hardware. |
| SW_CAMERA_LENS_COVER |
"set = lens covered" |
| SW_DOCK |
"set = plugged into doc" |
| SW_FRONT_PROXIMITY |
"set = front proximity sensor active" |
| SW_HEADPHONE_INSERT |
"set = inserted" |
| SW_JACK_PHYSICAL_INSERT |
"set = mechanical switch set" |
| SW_KEYPAD_SLIDE |
"set = keypad slide out" |
| SW_LID |
"set = lid shut" |
| SW_LINEIN_INSERT |
"set = inserted" |
| SW_LINEOUT_INSERT |
"set = inserted" |
| SW_MAX | |
| SW_MICROPHONE_INSERT |
"set = inserted" |
| SW_MUTE_DEVICE |
"set = device disabled" |
| SW_PEN_INSERTED |
"set = pen inserted" |
| SW_RFKILL_ALL |
"rfkill master switch, type 'any'" |
| SW_ROTATE_LOCK |
"set = rotate locked/disabled" |
| SW_TABLET_MODE |
"set = tablet mode" |
| SW_VIDEOOUT_INSERT |
"set = inserted" |
| SYNCHRONIZATION |
A bookkeeping event. Usually not important to applications. |
| TOPBUTTONPAD |
"softbuttons at top of pad", according to the header. |
Functions
| enumerate |
Crawls |