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