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 if this was a middle click
288 ///
289 /// `Keyboard`: false
290 /// `Mouse`: Whether the middle button was pressed and released
291 pub fn is_middle_click(&self) -> bool {
292 match self {
293 ClickEvent::Keyboard(_) => false,
294 ClickEvent::Mouse(event) => {
295 event.down.button == MouseButton::Middle && event.up.button == MouseButton::Middle
296 }
297 }
298 }
299
300 /// Returns whether the click was a standard click
301 ///
302 /// `Keyboard`: Always true
303 /// `Mouse`: Left button pressed and released
304 pub fn standard_click(&self) -> bool {
305 match self {
306 ClickEvent::Keyboard(_) => true,
307 ClickEvent::Mouse(event) => {
308 event.down.button == MouseButton::Left && event.up.button == MouseButton::Left
309 }
310 }
311 }
312
313 /// Returns whether the click focused the element
314 ///
315 /// `Keyboard`: false, keyboard clicks only work if an element is already focused
316 /// `Mouse`: Whether this was the first focusing click
317 pub fn first_focus(&self) -> bool {
318 match self {
319 ClickEvent::Keyboard(_) => false,
320 ClickEvent::Mouse(event) => event.down.first_mouse,
321 }
322 }
323
324 /// Returns the click count of the click event
325 ///
326 /// `Keyboard`: Always 1
327 /// `Mouse`: Count of clicks from MouseUpEvent
328 pub fn click_count(&self) -> usize {
329 match self {
330 ClickEvent::Keyboard(_) => 1,
331 ClickEvent::Mouse(event) => event.up.click_count,
332 }
333 }
334
335 /// Returns whether the click event is generated by a keyboard event
336 pub fn is_keyboard(&self) -> bool {
337 match self {
338 ClickEvent::Mouse(_) => false,
339 ClickEvent::Keyboard(_) => true,
340 }
341 }
342}
343
344/// An enum representing the keyboard button that was pressed for a click event.
345#[derive(Hash, PartialEq, Eq, Copy, Clone, Debug, Default)]
346pub enum KeyboardButton {
347 /// Enter key was clicked
348 #[default]
349 Enter,
350 /// Space key was clicked
351 Space,
352}
353
354/// An enum representing the mouse button that was pressed.
355#[derive(Hash, Default, PartialEq, Eq, Copy, Clone, Debug)]
356pub enum MouseButton {
357 /// The left mouse button.
358 #[default]
359 Left,
360
361 /// The right mouse button.
362 Right,
363
364 /// The middle mouse button.
365 Middle,
366
367 /// A navigation button, such as back or forward.
368 Navigate(NavigationDirection),
369}
370
371impl MouseButton {
372 /// Get all the mouse buttons in a list.
373 pub fn all() -> Vec<Self> {
374 vec![
375 MouseButton::Left,
376 MouseButton::Right,
377 MouseButton::Middle,
378 MouseButton::Navigate(NavigationDirection::Back),
379 MouseButton::Navigate(NavigationDirection::Forward),
380 ]
381 }
382}
383
384/// A navigation direction, such as back or forward.
385#[derive(Hash, Default, PartialEq, Eq, Copy, Clone, Debug)]
386pub enum NavigationDirection {
387 /// The back button.
388 #[default]
389 Back,
390
391 /// The forward button.
392 Forward,
393}
394
395/// A mouse move event from the platform.
396#[derive(Clone, Debug, Default)]
397pub struct MouseMoveEvent {
398 /// The position of the mouse on the window.
399 pub position: Point<Pixels>,
400
401 /// The mouse button that was pressed, if any.
402 pub pressed_button: Option<MouseButton>,
403
404 /// The modifiers that were held down when the mouse was moved.
405 pub modifiers: Modifiers,
406}
407
408impl Sealed for MouseMoveEvent {}
409impl InputEvent for MouseMoveEvent {
410 fn to_platform_input(self) -> PlatformInput {
411 PlatformInput::MouseMove(self)
412 }
413}
414impl MouseEvent for MouseMoveEvent {}
415
416impl MouseMoveEvent {
417 /// Returns true if the left mouse button is currently held down.
418 pub fn dragging(&self) -> bool {
419 self.pressed_button == Some(MouseButton::Left)
420 }
421}
422
423/// A mouse wheel event from the platform.
424#[derive(Clone, Debug, Default)]
425pub struct ScrollWheelEvent {
426 /// The position of the mouse on the window.
427 pub position: Point<Pixels>,
428
429 /// The change in scroll wheel position for this event.
430 pub delta: ScrollDelta,
431
432 /// The modifiers that were held down when the mouse was moved.
433 pub modifiers: Modifiers,
434
435 /// The phase of the touch event.
436 pub touch_phase: TouchPhase,
437}
438
439impl Sealed for ScrollWheelEvent {}
440impl InputEvent for ScrollWheelEvent {
441 fn to_platform_input(self) -> PlatformInput {
442 PlatformInput::ScrollWheel(self)
443 }
444}
445impl MouseEvent for ScrollWheelEvent {}
446
447impl Deref for ScrollWheelEvent {
448 type Target = Modifiers;
449
450 fn deref(&self) -> &Self::Target {
451 &self.modifiers
452 }
453}
454
455/// The scroll delta for a scroll wheel event.
456#[derive(Clone, Copy, Debug)]
457pub enum ScrollDelta {
458 /// An exact scroll delta in pixels.
459 Pixels(Point<Pixels>),
460 /// An inexact scroll delta in lines.
461 Lines(Point<f32>),
462}
463
464impl Default for ScrollDelta {
465 fn default() -> Self {
466 Self::Lines(Default::default())
467 }
468}
469
470impl ScrollDelta {
471 /// Returns true if this is a precise scroll delta in pixels.
472 pub fn precise(&self) -> bool {
473 match self {
474 ScrollDelta::Pixels(_) => true,
475 ScrollDelta::Lines(_) => false,
476 }
477 }
478
479 /// Converts this scroll event into exact pixels.
480 pub fn pixel_delta(&self, line_height: Pixels) -> Point<Pixels> {
481 match self {
482 ScrollDelta::Pixels(delta) => *delta,
483 ScrollDelta::Lines(delta) => point(line_height * delta.x, line_height * delta.y),
484 }
485 }
486
487 /// Combines two scroll deltas into one.
488 /// If the signs of the deltas are the same (both positive or both negative),
489 /// the deltas are added together. If the signs are opposite, the second delta
490 /// (other) is used, effectively overriding the first delta.
491 pub fn coalesce(self, other: ScrollDelta) -> ScrollDelta {
492 match (self, other) {
493 (ScrollDelta::Pixels(a), ScrollDelta::Pixels(b)) => {
494 let x = if a.x.signum() == b.x.signum() {
495 a.x + b.x
496 } else {
497 b.x
498 };
499
500 let y = if a.y.signum() == b.y.signum() {
501 a.y + b.y
502 } else {
503 b.y
504 };
505
506 ScrollDelta::Pixels(point(x, y))
507 }
508
509 (ScrollDelta::Lines(a), ScrollDelta::Lines(b)) => {
510 let x = if a.x.signum() == b.x.signum() {
511 a.x + b.x
512 } else {
513 b.x
514 };
515
516 let y = if a.y.signum() == b.y.signum() {
517 a.y + b.y
518 } else {
519 b.y
520 };
521
522 ScrollDelta::Lines(point(x, y))
523 }
524
525 _ => other,
526 }
527 }
528}
529
530/// A mouse exit event from the platform, generated when the mouse leaves the window.
531#[derive(Clone, Debug, Default)]
532pub struct MouseExitEvent {
533 /// The position of the mouse relative to the window.
534 pub position: Point<Pixels>,
535 /// The mouse button that was pressed, if any.
536 pub pressed_button: Option<MouseButton>,
537 /// The modifiers that were held down when the mouse was moved.
538 pub modifiers: Modifiers,
539}
540
541impl Sealed for MouseExitEvent {}
542impl InputEvent for MouseExitEvent {
543 fn to_platform_input(self) -> PlatformInput {
544 PlatformInput::MouseExited(self)
545 }
546}
547
548impl MouseEvent for MouseExitEvent {}
549
550impl Deref for MouseExitEvent {
551 type Target = Modifiers;
552
553 fn deref(&self) -> &Self::Target {
554 &self.modifiers
555 }
556}
557
558/// A collection of paths from the platform, such as from a file drop.
559#[derive(Debug, Clone, Default, Eq, PartialEq)]
560pub struct ExternalPaths(pub SmallVec<[PathBuf; 2]>);
561
562impl ExternalPaths {
563 /// Convert this collection of paths into a slice.
564 pub fn paths(&self) -> &[PathBuf] {
565 &self.0
566 }
567}
568
569impl Render for ExternalPaths {
570 fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
571 // the platform will render icons for the dragged files
572 Empty
573 }
574}
575
576/// A file drop event from the platform, generated when files are dragged and dropped onto the window.
577#[derive(Debug, Clone)]
578pub enum FileDropEvent {
579 /// The files have entered the window.
580 Entered {
581 /// The position of the mouse relative to the window.
582 position: Point<Pixels>,
583 /// The paths of the files that are being dragged.
584 paths: ExternalPaths,
585 },
586 /// The files are being dragged over the window
587 Pending {
588 /// The position of the mouse relative to the window.
589 position: Point<Pixels>,
590 },
591 /// The files have been dropped onto the window.
592 Submit {
593 /// The position of the mouse relative to the window.
594 position: Point<Pixels>,
595 },
596 /// The user has stopped dragging the files over the window.
597 Exited,
598}
599
600impl Sealed for FileDropEvent {}
601impl InputEvent for FileDropEvent {
602 fn to_platform_input(self) -> PlatformInput {
603 PlatformInput::FileDrop(self)
604 }
605}
606impl MouseEvent for FileDropEvent {}
607
608/// An enum corresponding to all kinds of platform input events.
609#[derive(Clone, Debug)]
610pub enum PlatformInput {
611 /// A key was pressed.
612 KeyDown(KeyDownEvent),
613 /// A key was released.
614 KeyUp(KeyUpEvent),
615 /// The keyboard modifiers were changed.
616 ModifiersChanged(ModifiersChangedEvent),
617 /// The mouse was pressed.
618 MouseDown(MouseDownEvent),
619 /// The mouse was released.
620 MouseUp(MouseUpEvent),
621 /// Mouse pressure.
622 MousePressure(MousePressureEvent),
623 /// The mouse was moved.
624 MouseMove(MouseMoveEvent),
625 /// The mouse exited the window.
626 MouseExited(MouseExitEvent),
627 /// The scroll wheel was used.
628 ScrollWheel(ScrollWheelEvent),
629 /// Files were dragged and dropped onto the window.
630 FileDrop(FileDropEvent),
631}
632
633impl PlatformInput {
634 pub(crate) fn mouse_event(&self) -> Option<&dyn Any> {
635 match self {
636 PlatformInput::KeyDown { .. } => None,
637 PlatformInput::KeyUp { .. } => None,
638 PlatformInput::ModifiersChanged { .. } => None,
639 PlatformInput::MouseDown(event) => Some(event),
640 PlatformInput::MouseUp(event) => Some(event),
641 PlatformInput::MouseMove(event) => Some(event),
642 PlatformInput::MousePressure(event) => Some(event),
643 PlatformInput::MouseExited(event) => Some(event),
644 PlatformInput::ScrollWheel(event) => Some(event),
645 PlatformInput::FileDrop(event) => Some(event),
646 }
647 }
648
649 pub(crate) fn keyboard_event(&self) -> Option<&dyn Any> {
650 match self {
651 PlatformInput::KeyDown(event) => Some(event),
652 PlatformInput::KeyUp(event) => Some(event),
653 PlatformInput::ModifiersChanged(event) => Some(event),
654 PlatformInput::MouseDown(_) => None,
655 PlatformInput::MouseUp(_) => None,
656 PlatformInput::MouseMove(_) => None,
657 PlatformInput::MousePressure(_) => None,
658 PlatformInput::MouseExited(_) => None,
659 PlatformInput::ScrollWheel(_) => None,
660 PlatformInput::FileDrop(_) => None,
661 }
662 }
663}
664
665#[cfg(test)]
666mod test {
667
668 use crate::{
669 self as gpui, AppContext as _, Context, FocusHandle, InteractiveElement, IntoElement,
670 KeyBinding, Keystroke, ParentElement, Render, TestAppContext, Window, div,
671 };
672
673 struct TestView {
674 saw_key_down: bool,
675 saw_action: bool,
676 focus_handle: FocusHandle,
677 }
678
679 actions!(test_only, [TestAction]);
680
681 impl Render for TestView {
682 fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
683 div().id("testview").child(
684 div()
685 .key_context("parent")
686 .on_key_down(cx.listener(|this, _, _, cx| {
687 cx.stop_propagation();
688 this.saw_key_down = true
689 }))
690 .on_action(cx.listener(|this: &mut TestView, _: &TestAction, _, _| {
691 this.saw_action = true
692 }))
693 .child(
694 div()
695 .key_context("nested")
696 .track_focus(&self.focus_handle)
697 .into_element(),
698 ),
699 )
700 }
701 }
702
703 #[gpui::test]
704 fn test_on_events(cx: &mut TestAppContext) {
705 let window = cx.update(|cx| {
706 cx.open_window(Default::default(), |_, cx| {
707 cx.new(|cx| TestView {
708 saw_key_down: false,
709 saw_action: false,
710 focus_handle: cx.focus_handle(),
711 })
712 })
713 .unwrap()
714 });
715
716 cx.update(|cx| {
717 cx.bind_keys(vec![KeyBinding::new("ctrl-g", TestAction, Some("parent"))]);
718 });
719
720 window
721 .update(cx, |test_view, window, cx| {
722 window.focus(&test_view.focus_handle, cx)
723 })
724 .unwrap();
725
726 cx.dispatch_keystroke(*window, Keystroke::parse("a").unwrap());
727 cx.dispatch_keystroke(*window, Keystroke::parse("ctrl-g").unwrap());
728
729 window
730 .update(cx, |test_view, _, _| {
731 assert!(test_view.saw_key_down || test_view.saw_action);
732 assert!(test_view.saw_key_down);
733 assert!(test_view.saw_action);
734 })
735 .unwrap();
736 }
737}