1use crate::{
2 Bounds, Capslock, Context, Empty, IntoElement, Keystroke, Modifiers, Pixels, Point, Render,
3 Window, point, seal::Sealed,
4};
5use smallvec::SmallVec;
6use std::{any::Any, fmt::Debug, ops::Deref, path::PathBuf};
7
8/// An event from a platform input source.
9pub trait InputEvent: Sealed + 'static {
10 /// Convert this event into the platform input enum.
11 fn to_platform_input(self) -> PlatformInput;
12}
13
14/// A key event from the platform.
15pub trait KeyEvent: InputEvent {}
16
17/// A mouse event from the platform.
18pub trait MouseEvent: InputEvent {}
19
20/// The key down event equivalent for the platform.
21#[derive(Clone, Debug, Eq, PartialEq)]
22pub struct KeyDownEvent {
23 /// The keystroke that was generated.
24 pub keystroke: Keystroke,
25
26 /// Whether the key is currently held down.
27 pub is_held: bool,
28}
29
30impl Sealed for KeyDownEvent {}
31impl InputEvent for KeyDownEvent {
32 fn to_platform_input(self) -> PlatformInput {
33 PlatformInput::KeyDown(self)
34 }
35}
36impl KeyEvent for KeyDownEvent {}
37
38/// The key up event equivalent for the platform.
39#[derive(Clone, Debug)]
40pub struct KeyUpEvent {
41 /// The keystroke that was released.
42 pub keystroke: Keystroke,
43}
44
45impl Sealed for KeyUpEvent {}
46impl InputEvent for KeyUpEvent {
47 fn to_platform_input(self) -> PlatformInput {
48 PlatformInput::KeyUp(self)
49 }
50}
51impl KeyEvent for KeyUpEvent {}
52
53/// The modifiers changed event equivalent for the platform.
54#[derive(Clone, Debug, Default)]
55pub struct ModifiersChangedEvent {
56 /// The new state of the modifier keys
57 pub modifiers: Modifiers,
58 /// The new state of the capslock key
59 pub capslock: Capslock,
60}
61
62impl Sealed for ModifiersChangedEvent {}
63impl InputEvent for ModifiersChangedEvent {
64 fn to_platform_input(self) -> PlatformInput {
65 PlatformInput::ModifiersChanged(self)
66 }
67}
68impl KeyEvent for ModifiersChangedEvent {}
69
70impl Deref for ModifiersChangedEvent {
71 type Target = Modifiers;
72
73 fn deref(&self) -> &Self::Target {
74 &self.modifiers
75 }
76}
77
78/// The phase of a touch motion event.
79/// Based on the winit enum of the same name.
80#[derive(Clone, Copy, Debug, Default)]
81pub enum TouchPhase {
82 /// The touch started.
83 Started,
84 /// The touch event is moving.
85 #[default]
86 Moved,
87 /// The touch phase has ended
88 Ended,
89}
90
91/// A mouse down event from the platform
92#[derive(Clone, Debug, Default)]
93pub struct MouseDownEvent {
94 /// Which mouse button was pressed.
95 pub button: MouseButton,
96
97 /// The position of the mouse on the window.
98 pub position: Point<Pixels>,
99
100 /// The modifiers that were held down when the mouse was pressed.
101 pub modifiers: Modifiers,
102
103 /// The number of times the button has been clicked.
104 pub click_count: usize,
105
106 /// Whether this is the first, focusing click.
107 pub first_mouse: bool,
108}
109
110impl Sealed for MouseDownEvent {}
111impl InputEvent for MouseDownEvent {
112 fn to_platform_input(self) -> PlatformInput {
113 PlatformInput::MouseDown(self)
114 }
115}
116impl MouseEvent for MouseDownEvent {}
117
118/// A mouse up event from the platform
119#[derive(Clone, Debug, Default)]
120pub struct MouseUpEvent {
121 /// Which mouse button was released.
122 pub button: MouseButton,
123
124 /// The position of the mouse on the window.
125 pub position: Point<Pixels>,
126
127 /// The modifiers that were held down when the mouse was released.
128 pub modifiers: Modifiers,
129
130 /// The number of times the button has been clicked.
131 pub click_count: usize,
132}
133
134impl Sealed for MouseUpEvent {}
135impl InputEvent for MouseUpEvent {
136 fn to_platform_input(self) -> PlatformInput {
137 PlatformInput::MouseUp(self)
138 }
139}
140impl MouseEvent for MouseUpEvent {}
141
142/// A click event, generated when a mouse button is pressed and released.
143#[derive(Clone, Debug, Default)]
144pub struct MouseClickEvent {
145 /// The mouse event when the button was pressed.
146 pub down: MouseDownEvent,
147
148 /// The mouse event when the button was released.
149 pub up: MouseUpEvent,
150}
151
152/// A click event that was generated by a keyboard button being pressed and released.
153#[derive(Clone, Debug)]
154pub struct KeyboardClickEvent {
155 /// The keyboard button that was pressed to trigger the click.
156 pub button: KeyboardButton,
157
158 /// The bounds of the element that was clicked.
159 pub bounds: Bounds<Pixels>,
160}
161
162/// A click event, generated when a mouse button or keyboard button is pressed and released.
163#[derive(Clone, Debug)]
164pub enum ClickEvent {
165 /// A click event trigger by a mouse button being pressed and released.
166 Mouse(MouseClickEvent),
167 /// A click event trigger by a keyboard button being pressed and released.
168 Keyboard(KeyboardClickEvent),
169}
170
171impl ClickEvent {
172 /// Returns the modifiers that were held during the click event
173 ///
174 /// `Keyboard`: The keyboard click events never have modifiers.
175 /// `Mouse`: Modifiers that were held during the mouse key up event.
176 pub fn modifiers(&self) -> Modifiers {
177 match self {
178 // Click events are only generated from keyboard events _without any modifiers_, so we know the modifiers are always Default
179 ClickEvent::Keyboard(_) => Modifiers::default(),
180 // Click events on the web only reflect the modifiers for the keyup event,
181 // tested via observing the behavior of the `ClickEvent.shiftKey` field in Chrome 138
182 // under various combinations of modifiers and keyUp / keyDown events.
183 ClickEvent::Mouse(event) => event.up.modifiers,
184 }
185 }
186
187 /// Returns the position of the click event
188 ///
189 /// `Keyboard`: The bottom left corner of the clicked hitbox
190 /// `Mouse`: The position of the mouse when the button was released.
191 pub fn position(&self) -> Point<Pixels> {
192 match self {
193 ClickEvent::Keyboard(event) => event.bounds.bottom_left(),
194 ClickEvent::Mouse(event) => event.up.position,
195 }
196 }
197
198 /// Returns the mouse position of the click event
199 ///
200 /// `Keyboard`: None
201 /// `Mouse`: The position of the mouse when the button was released.
202 pub fn mouse_position(&self) -> Option<Point<Pixels>> {
203 match self {
204 ClickEvent::Keyboard(_) => None,
205 ClickEvent::Mouse(event) => Some(event.up.position),
206 }
207 }
208
209 /// Returns if this was a right click
210 ///
211 /// `Keyboard`: false
212 /// `Mouse`: Whether the right button was pressed and released
213 pub fn is_right_click(&self) -> bool {
214 match self {
215 ClickEvent::Keyboard(_) => false,
216 ClickEvent::Mouse(event) => {
217 event.down.button == MouseButton::Right && event.up.button == MouseButton::Right
218 }
219 }
220 }
221
222 /// Returns whether the click was a standard click
223 ///
224 /// `Keyboard`: Always true
225 /// `Mouse`: Left button pressed and released
226 pub fn standard_click(&self) -> bool {
227 match self {
228 ClickEvent::Keyboard(_) => true,
229 ClickEvent::Mouse(event) => {
230 event.down.button == MouseButton::Left && event.up.button == MouseButton::Left
231 }
232 }
233 }
234
235 /// Returns whether the click focused the element
236 ///
237 /// `Keyboard`: false, keyboard clicks only work if an element is already focused
238 /// `Mouse`: Whether this was the first focusing click
239 pub fn first_focus(&self) -> bool {
240 match self {
241 ClickEvent::Keyboard(_) => false,
242 ClickEvent::Mouse(event) => event.down.first_mouse,
243 }
244 }
245
246 /// Returns the click count of the click event
247 ///
248 /// `Keyboard`: Always 1
249 /// `Mouse`: Count of clicks from MouseUpEvent
250 pub fn click_count(&self) -> usize {
251 match self {
252 ClickEvent::Keyboard(_) => 1,
253 ClickEvent::Mouse(event) => event.up.click_count,
254 }
255 }
256}
257
258/// An enum representing the keyboard button that was pressed for a click event.
259#[derive(Hash, PartialEq, Eq, Copy, Clone, Debug)]
260pub enum KeyboardButton {
261 /// Enter key was clicked
262 Enter,
263 /// Space key was clicked
264 Space,
265}
266
267/// An enum representing the mouse button that was pressed.
268#[derive(Hash, PartialEq, Eq, Copy, Clone, Debug)]
269pub enum MouseButton {
270 /// The left mouse button.
271 Left,
272
273 /// The right mouse button.
274 Right,
275
276 /// The middle mouse button.
277 Middle,
278
279 /// A navigation button, such as back or forward.
280 Navigate(NavigationDirection),
281}
282
283impl MouseButton {
284 /// Get all the mouse buttons in a list.
285 pub fn all() -> Vec<Self> {
286 vec![
287 MouseButton::Left,
288 MouseButton::Right,
289 MouseButton::Middle,
290 MouseButton::Navigate(NavigationDirection::Back),
291 MouseButton::Navigate(NavigationDirection::Forward),
292 ]
293 }
294}
295
296impl Default for MouseButton {
297 fn default() -> Self {
298 Self::Left
299 }
300}
301
302/// A navigation direction, such as back or forward.
303#[derive(Hash, PartialEq, Eq, Copy, Clone, Debug)]
304pub enum NavigationDirection {
305 /// The back button.
306 Back,
307
308 /// The forward button.
309 Forward,
310}
311
312impl Default for NavigationDirection {
313 fn default() -> Self {
314 Self::Back
315 }
316}
317
318/// A mouse move event from the platform
319#[derive(Clone, Debug, Default)]
320pub struct MouseMoveEvent {
321 /// The position of the mouse on the window.
322 pub position: Point<Pixels>,
323
324 /// The mouse button that was pressed, if any.
325 pub pressed_button: Option<MouseButton>,
326
327 /// The modifiers that were held down when the mouse was moved.
328 pub modifiers: Modifiers,
329}
330
331impl Sealed for MouseMoveEvent {}
332impl InputEvent for MouseMoveEvent {
333 fn to_platform_input(self) -> PlatformInput {
334 PlatformInput::MouseMove(self)
335 }
336}
337impl MouseEvent for MouseMoveEvent {}
338
339impl MouseMoveEvent {
340 /// Returns true if the left mouse button is currently held down.
341 pub fn dragging(&self) -> bool {
342 self.pressed_button == Some(MouseButton::Left)
343 }
344}
345
346/// A mouse wheel event from the platform
347#[derive(Clone, Debug, Default)]
348pub struct ScrollWheelEvent {
349 /// The position of the mouse on the window.
350 pub position: Point<Pixels>,
351
352 /// The change in scroll wheel position for this event.
353 pub delta: ScrollDelta,
354
355 /// The modifiers that were held down when the mouse was moved.
356 pub modifiers: Modifiers,
357
358 /// The phase of the touch event.
359 pub touch_phase: TouchPhase,
360}
361
362impl Sealed for ScrollWheelEvent {}
363impl InputEvent for ScrollWheelEvent {
364 fn to_platform_input(self) -> PlatformInput {
365 PlatformInput::ScrollWheel(self)
366 }
367}
368impl MouseEvent for ScrollWheelEvent {}
369
370impl Deref for ScrollWheelEvent {
371 type Target = Modifiers;
372
373 fn deref(&self) -> &Self::Target {
374 &self.modifiers
375 }
376}
377
378/// The scroll delta for a scroll wheel event.
379#[derive(Clone, Copy, Debug)]
380pub enum ScrollDelta {
381 /// An exact scroll delta in pixels.
382 Pixels(Point<Pixels>),
383 /// An inexact scroll delta in lines.
384 Lines(Point<f32>),
385}
386
387impl Default for ScrollDelta {
388 fn default() -> Self {
389 Self::Lines(Default::default())
390 }
391}
392
393impl ScrollDelta {
394 /// Returns true if this is a precise scroll delta in pixels.
395 pub fn precise(&self) -> bool {
396 match self {
397 ScrollDelta::Pixels(_) => true,
398 ScrollDelta::Lines(_) => false,
399 }
400 }
401
402 /// Converts this scroll event into exact pixels.
403 pub fn pixel_delta(&self, line_height: Pixels) -> Point<Pixels> {
404 match self {
405 ScrollDelta::Pixels(delta) => *delta,
406 ScrollDelta::Lines(delta) => point(line_height * delta.x, line_height * delta.y),
407 }
408 }
409
410 /// Combines two scroll deltas into one.
411 /// If the signs of the deltas are the same (both positive or both negative),
412 /// the deltas are added together. If the signs are opposite, the second delta
413 /// (other) is used, effectively overriding the first delta.
414 pub fn coalesce(self, other: ScrollDelta) -> ScrollDelta {
415 match (self, other) {
416 (ScrollDelta::Pixels(a), ScrollDelta::Pixels(b)) => {
417 let x = if a.x.signum() == b.x.signum() {
418 a.x + b.x
419 } else {
420 b.x
421 };
422
423 let y = if a.y.signum() == b.y.signum() {
424 a.y + b.y
425 } else {
426 b.y
427 };
428
429 ScrollDelta::Pixels(point(x, y))
430 }
431
432 (ScrollDelta::Lines(a), ScrollDelta::Lines(b)) => {
433 let x = if a.x.signum() == b.x.signum() {
434 a.x + b.x
435 } else {
436 b.x
437 };
438
439 let y = if a.y.signum() == b.y.signum() {
440 a.y + b.y
441 } else {
442 b.y
443 };
444
445 ScrollDelta::Lines(point(x, y))
446 }
447
448 _ => other,
449 }
450 }
451}
452
453/// A mouse exit event from the platform, generated when the mouse leaves the window.
454#[derive(Clone, Debug, Default)]
455pub struct MouseExitEvent {
456 /// The position of the mouse relative to the window.
457 pub position: Point<Pixels>,
458 /// The mouse button that was pressed, if any.
459 pub pressed_button: Option<MouseButton>,
460 /// The modifiers that were held down when the mouse was moved.
461 pub modifiers: Modifiers,
462}
463
464impl Sealed for MouseExitEvent {}
465impl InputEvent for MouseExitEvent {
466 fn to_platform_input(self) -> PlatformInput {
467 PlatformInput::MouseExited(self)
468 }
469}
470impl MouseEvent for MouseExitEvent {}
471
472impl Deref for MouseExitEvent {
473 type Target = Modifiers;
474
475 fn deref(&self) -> &Self::Target {
476 &self.modifiers
477 }
478}
479
480/// A collection of paths from the platform, such as from a file drop.
481#[derive(Debug, Clone, Default)]
482pub struct ExternalPaths(pub(crate) SmallVec<[PathBuf; 2]>);
483
484impl ExternalPaths {
485 /// Convert this collection of paths into a slice.
486 pub fn paths(&self) -> &[PathBuf] {
487 &self.0
488 }
489}
490
491impl Render for ExternalPaths {
492 fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
493 // the platform will render icons for the dragged files
494 Empty
495 }
496}
497
498/// A file drop event from the platform, generated when files are dragged and dropped onto the window.
499#[derive(Debug, Clone)]
500pub enum FileDropEvent {
501 /// The files have entered the window.
502 Entered {
503 /// The position of the mouse relative to the window.
504 position: Point<Pixels>,
505 /// The paths of the files that are being dragged.
506 paths: ExternalPaths,
507 },
508 /// The files are being dragged over the window
509 Pending {
510 /// The position of the mouse relative to the window.
511 position: Point<Pixels>,
512 },
513 /// The files have been dropped onto the window.
514 Submit {
515 /// The position of the mouse relative to the window.
516 position: Point<Pixels>,
517 },
518 /// The user has stopped dragging the files over the window.
519 Exited,
520}
521
522impl Sealed for FileDropEvent {}
523impl InputEvent for FileDropEvent {
524 fn to_platform_input(self) -> PlatformInput {
525 PlatformInput::FileDrop(self)
526 }
527}
528impl MouseEvent for FileDropEvent {}
529
530/// An enum corresponding to all kinds of platform input events.
531#[derive(Clone, Debug)]
532pub enum PlatformInput {
533 /// A key was pressed.
534 KeyDown(KeyDownEvent),
535 /// A key was released.
536 KeyUp(KeyUpEvent),
537 /// The keyboard modifiers were changed.
538 ModifiersChanged(ModifiersChangedEvent),
539 /// The mouse was pressed.
540 MouseDown(MouseDownEvent),
541 /// The mouse was released.
542 MouseUp(MouseUpEvent),
543 /// The mouse was moved.
544 MouseMove(MouseMoveEvent),
545 /// The mouse exited the window.
546 MouseExited(MouseExitEvent),
547 /// The scroll wheel was used.
548 ScrollWheel(ScrollWheelEvent),
549 /// Files were dragged and dropped onto the window.
550 FileDrop(FileDropEvent),
551}
552
553impl PlatformInput {
554 pub(crate) fn mouse_event(&self) -> Option<&dyn Any> {
555 match self {
556 PlatformInput::KeyDown { .. } => None,
557 PlatformInput::KeyUp { .. } => None,
558 PlatformInput::ModifiersChanged { .. } => None,
559 PlatformInput::MouseDown(event) => Some(event),
560 PlatformInput::MouseUp(event) => Some(event),
561 PlatformInput::MouseMove(event) => Some(event),
562 PlatformInput::MouseExited(event) => Some(event),
563 PlatformInput::ScrollWheel(event) => Some(event),
564 PlatformInput::FileDrop(event) => Some(event),
565 }
566 }
567
568 pub(crate) fn keyboard_event(&self) -> Option<&dyn Any> {
569 match self {
570 PlatformInput::KeyDown(event) => Some(event),
571 PlatformInput::KeyUp(event) => Some(event),
572 PlatformInput::ModifiersChanged(event) => Some(event),
573 PlatformInput::MouseDown(_) => None,
574 PlatformInput::MouseUp(_) => None,
575 PlatformInput::MouseMove(_) => None,
576 PlatformInput::MouseExited(_) => None,
577 PlatformInput::ScrollWheel(_) => None,
578 PlatformInput::FileDrop(_) => None,
579 }
580 }
581}
582
583#[cfg(test)]
584mod test {
585
586 use crate::{
587 self as gpui, AppContext as _, Context, FocusHandle, InteractiveElement, IntoElement,
588 KeyBinding, Keystroke, ParentElement, Render, TestAppContext, Window, div,
589 };
590
591 struct TestView {
592 saw_key_down: bool,
593 saw_action: bool,
594 focus_handle: FocusHandle,
595 }
596
597 actions!(test_only, [TestAction]);
598
599 impl Render for TestView {
600 fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
601 div().id("testview").child(
602 div()
603 .key_context("parent")
604 .on_key_down(cx.listener(|this, _, _, cx| {
605 cx.stop_propagation();
606 this.saw_key_down = true
607 }))
608 .on_action(cx.listener(|this: &mut TestView, _: &TestAction, _, _| {
609 this.saw_action = true
610 }))
611 .child(
612 div()
613 .key_context("nested")
614 .track_focus(&self.focus_handle)
615 .into_element(),
616 ),
617 )
618 }
619 }
620
621 #[gpui::test]
622 fn test_on_events(cx: &mut TestAppContext) {
623 let window = cx.update(|cx| {
624 cx.open_window(Default::default(), |_, cx| {
625 cx.new(|cx| TestView {
626 saw_key_down: false,
627 saw_action: false,
628 focus_handle: cx.focus_handle(),
629 })
630 })
631 .unwrap()
632 });
633
634 cx.update(|cx| {
635 cx.bind_keys(vec![KeyBinding::new("ctrl-g", TestAction, Some("parent"))]);
636 });
637
638 window
639 .update(cx, |test_view, window, _cx| {
640 window.focus(&test_view.focus_handle)
641 })
642 .unwrap();
643
644 cx.dispatch_keystroke(*window, Keystroke::parse("a").unwrap());
645 cx.dispatch_keystroke(*window, Keystroke::parse("ctrl-g").unwrap());
646
647 window
648 .update(cx, |test_view, _, _| {
649 assert!(test_view.saw_key_down || test_view.saw_action);
650 assert!(test_view.saw_key_down);
651 assert!(test_view.saw_action);
652 })
653 .unwrap();
654 }
655}