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