egui/data/input/event.rs
1use epaint::ColorImage;
2
3use crate::{
4 Key,
5 emath::{Pos2, Vec2},
6};
7
8use super::{
9 ImeEvent, Modifiers, MouseWheelUnit, PointerButton, TouchDeviceId, TouchId, TouchPhase,
10};
11
12/// An input event generated by the integration.
13///
14/// This only covers events that egui cares about.
15#[derive(Clone, Debug, PartialEq)]
16#[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
17pub enum Event {
18 /// The integration detected a "copy" event (e.g. Cmd+C).
19 Copy,
20
21 /// The integration detected a "cut" event (e.g. Cmd+X).
22 Cut,
23
24 /// The integration detected a "paste" event (e.g. Cmd+V).
25 Paste(String),
26
27 /// Text input, e.g. via keyboard.
28 ///
29 /// When the user presses enter/return, do not send a [`Text`](Event::Text) (just [`Key::Enter`]).
30 Text(String),
31
32 /// A key was pressed or released.
33 ///
34 /// ## Note for integration authors
35 ///
36 /// Key events that has been processed by IMEs should not be sent to `egui`.
37 Key {
38 /// Most of the time, it's the logical key, heeding the active keymap -- for instance, if the user has Dvorak
39 /// keyboard layout, it will be taken into account.
40 ///
41 /// If it's impossible to determine the logical key on desktop platforms (say, in case of non-Latin letters),
42 /// `key` falls back to the value of the corresponding physical key. This is necessary for proper work of
43 /// standard shortcuts that only respond to Latin-based bindings (such as `Ctrl` + `V`).
44 key: Key,
45
46 /// The physical key, corresponding to the actual position on the keyboard.
47 ///
48 /// This ignores keymaps, so it is not recommended to use this.
49 /// The only thing it makes sense for is things like games,
50 /// where e.g. the physical location of WSAD on QWERTY should always map to movement,
51 /// even if the user is using Dvorak or AZERTY.
52 ///
53 /// `eframe` does not (yet) implement this on web.
54 physical_key: Option<Key>,
55
56 /// Was it pressed or released?
57 pressed: bool,
58
59 /// If this is a `pressed` event, is it a key-repeat?
60 ///
61 /// On many platforms, holding down a key produces many repeated "pressed" events for it, so called key-repeats.
62 /// Sometimes you will want to ignore such events, and this lets you do that.
63 ///
64 /// egui will automatically detect such repeat events and mark them as such here.
65 /// Therefore, if you are writing an egui integration, you do not need to set this (just set it to `false`).
66 repeat: bool,
67
68 /// The state of the modifier keys at the time of the event.
69 modifiers: Modifiers,
70 },
71
72 /// The set of held modifier keys changed.
73 ModifiersChanged(Modifiers),
74
75 /// The mouse or touch moved to a new place.
76 PointerMoved(Pos2),
77
78 /// The mouse moved, the units are unspecified.
79 /// Represents the actual movement of the mouse, without acceleration or clamped by screen edges.
80 /// `PointerMoved` and `MouseMoved` can be sent at the same time.
81 /// This event is optional. If the integration can not determine unfiltered motion it should not send this event.
82 MouseMoved(Vec2),
83
84 /// A mouse button was pressed or released (or a touch started or stopped).
85 PointerButton {
86 /// Where is the pointer?
87 pos: Pos2,
88
89 /// What mouse button? For touches, use [`PointerButton::Primary`].
90 button: PointerButton,
91
92 /// Was it the button/touch pressed this frame, or released?
93 pressed: bool,
94
95 /// The state of the modifier keys at the time of the event.
96 modifiers: Modifiers,
97 },
98
99 /// The mouse left the screen, or the last/primary touch input disappeared.
100 ///
101 /// This means there is no longer a cursor on the screen for hovering etc.
102 ///
103 /// On touch-up first send `PointerButton{pressed: false, …}` followed by `PointerLeft`.
104 PointerGone,
105
106 /// Zoom scale factor this frame (e.g. from a pinch gesture).
107 ///
108 /// * `zoom = 1`: no change.
109 /// * `zoom < 1`: pinch together
110 /// * `zoom > 1`: pinch spread
111 ///
112 /// Note that egui also implement zooming by holding `Ctrl` and scrolling the mouse wheel,
113 /// so integration need NOT emit this `Zoom` event in those cases, just [`Self::MouseWheel`].
114 ///
115 /// As a user, check [`crate::InputState::smooth_scroll_delta`] to see if the user did any zooming this frame.
116 Zoom(f32),
117
118 /// Rotation in radians this frame, measuring clockwise (e.g. from a rotation gesture).
119 Rotate(f32),
120
121 /// IME Event
122 Ime(ImeEvent),
123
124 /// On touch screens, report this *in addition to*
125 /// [`Self::PointerMoved`], [`Self::PointerButton`], [`Self::PointerGone`]
126 Touch {
127 /// Hashed device identifier (if available; may be zero).
128 /// Can be used to separate touches from different devices.
129 device_id: TouchDeviceId,
130
131 /// Unique identifier of a finger/pen. Value is stable from touch down
132 /// to lift-up
133 id: TouchId,
134
135 /// One of: start move end cancel.
136 phase: TouchPhase,
137
138 /// Position of the touch (or where the touch was last detected)
139 pos: Pos2,
140
141 /// Describes how hard the touch device was pressed. May always be `None` if the platform does
142 /// not support pressure sensitivity.
143 /// The value is in the range from 0.0 (no pressure) to 1.0 (maximum pressure).
144 force: Option<f32>,
145 },
146
147 /// A raw mouse wheel event as sent by the backend.
148 ///
149 /// Used for scrolling.
150 MouseWheel {
151 /// The unit of `delta`: points, lines, or pages.
152 unit: MouseWheelUnit,
153
154 /// The direction of the vector indicates how to move the _content_ that is being viewed.
155 /// So if you get positive values, the content being viewed should move to the right and down,
156 /// revealing new things to the left and up.
157 ///
158 /// A positive X-value indicates the content is being moved right,
159 /// as when swiping right on a touch-screen or track-pad with natural scrolling.
160 ///
161 /// A positive Y-value indicates the content is being moved down,
162 /// as when swiping down on a touch-screen or track-pad with natural scrolling.
163 delta: Vec2,
164
165 /// The phase of the scroll, useful for trackpads.
166 ///
167 /// If unknown set this to [`TouchPhase::Move`].
168 phase: TouchPhase,
169
170 /// The state of the modifier keys at the time of the event.
171 modifiers: Modifiers,
172 },
173
174 /// The native window gained or lost focused (e.g. the user clicked alt-tab).
175 WindowFocused(bool),
176
177 /// An assistive technology (e.g. screen reader) requested an action.
178 AccessKitActionRequest(accesskit::ActionRequest),
179
180 /// The reply of a screenshot requested with [`crate::ViewportCommand::Screenshot`].
181 Screenshot {
182 viewport_id: crate::ViewportId,
183
184 /// Whatever was passed to [`crate::ViewportCommand::Screenshot`].
185 user_data: crate::UserData,
186
187 image: std::sync::Arc<ColorImage>,
188 },
189}