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