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