gdk4/auto/
event.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{
6    ffi, AxisUse, Device, DeviceTool, Display, EventSequence, EventType, ModifierType, Seat,
7    Surface, TimeCoord,
8};
9use glib::{prelude::*, translate::*};
10
11glib::wrapper! {
12    /// Represents windowing system events.
13    ///
14    /// In GTK applications the events are handled automatically by toplevel
15    /// widgets and passed on to the event controllers of appropriate widgets,
16    /// so using [`Event`][crate::Event] and its related API is rarely needed.
17    ///
18    /// [`Event`][crate::Event] structs are immutable.
19    ///
20    /// This is an Abstract Base Class, you cannot instantiate it.
21    #[doc(alias = "GdkEvent")]
22    pub struct Event(Shared<ffi::GdkEvent>);
23
24    match fn {
25        ref => |ptr| ffi::gdk_event_ref(ptr),
26        unref => |ptr| ffi::gdk_event_unref(ptr),
27    }
28}
29
30impl StaticType for Event {
31    fn static_type() -> glib::Type {
32        unsafe { from_glib(ffi::gdk_event_get_type()) }
33    }
34}
35
36impl Event {
37    pub const NONE: Option<&'static Event> = None;
38
39    /// Extracts all axis values from an event.
40    ///
41    /// To find out which axes are used, use [`DeviceTool::axes()`][crate::DeviceTool::axes()]
42    /// on the device tool returned by [`device_tool()`][Self::device_tool()].
43    ///
44    /// # Returns
45    ///
46    /// [`true`] on success, otherwise [`false`]
47    ///
48    /// ## `axes`
49    /// the array of values for all axes
50    #[doc(alias = "gdk_event_get_axes")]
51    #[doc(alias = "get_axes")]
52    pub fn axes(&self) -> Option<Vec<f64>> {
53        unsafe {
54            let mut axes = std::ptr::null_mut();
55            let mut n_axes = std::mem::MaybeUninit::uninit();
56            let ret = from_glib(ffi::gdk_event_get_axes(
57                self.as_ref().to_glib_none().0,
58                &mut axes,
59                n_axes.as_mut_ptr(),
60            ));
61            if ret {
62                Some(FromGlibContainer::from_glib_none_num(
63                    axes,
64                    n_axes.assume_init() as _,
65                ))
66            } else {
67                None
68            }
69        }
70    }
71
72    /// Extract the axis value for a particular axis use from
73    /// an event structure.
74    ///
75    /// To find out which axes are used, use [`DeviceTool::axes()`][crate::DeviceTool::axes()]
76    /// on the device tool returned by [`device_tool()`][Self::device_tool()].
77    /// ## `axis_use`
78    /// the axis use to look for
79    ///
80    /// # Returns
81    ///
82    /// [`true`] if the specified axis was found, otherwise [`false`]
83    ///
84    /// ## `value`
85    /// location to store the value found
86    #[doc(alias = "gdk_event_get_axis")]
87    #[doc(alias = "get_axis")]
88    pub fn axis(&self, axis_use: AxisUse) -> Option<f64> {
89        unsafe {
90            let mut value = std::mem::MaybeUninit::uninit();
91            let ret = from_glib(ffi::gdk_event_get_axis(
92                self.as_ref().to_glib_none().0,
93                axis_use.into_glib(),
94                value.as_mut_ptr(),
95            ));
96            if ret {
97                Some(value.assume_init())
98            } else {
99                None
100            }
101        }
102    }
103
104    /// Returns the device of an event.
105    ///
106    /// # Returns
107    ///
108    /// a [`Device`][crate::Device]
109    #[doc(alias = "gdk_event_get_device")]
110    #[doc(alias = "get_device")]
111    pub fn device(&self) -> Option<Device> {
112        unsafe { from_glib_none(ffi::gdk_event_get_device(self.as_ref().to_glib_none().0)) }
113    }
114
115    /// Returns a [`DeviceTool`][crate::DeviceTool] representing the tool that
116    /// caused the event.
117    ///
118    /// If the was not generated by a device that supports
119    /// different tools (such as a tablet), this function will
120    /// return [`None`].
121    ///
122    /// Note: the [`DeviceTool`][crate::DeviceTool] will be constant during
123    /// the application lifetime, if settings must be stored
124    /// persistently across runs, see [`DeviceTool::serial()`][crate::DeviceTool::serial()].
125    ///
126    /// # Returns
127    ///
128    /// The current device tool
129    #[doc(alias = "gdk_event_get_device_tool")]
130    #[doc(alias = "get_device_tool")]
131    pub fn device_tool(&self) -> Option<DeviceTool> {
132        unsafe {
133            from_glib_none(ffi::gdk_event_get_device_tool(
134                self.as_ref().to_glib_none().0,
135            ))
136        }
137    }
138
139    /// Retrieves the display associated to the @self.
140    ///
141    /// # Returns
142    ///
143    /// a [`Display`][crate::Display]
144    #[doc(alias = "gdk_event_get_display")]
145    #[doc(alias = "get_display")]
146    pub fn display(&self) -> Option<Display> {
147        unsafe { from_glib_none(ffi::gdk_event_get_display(self.as_ref().to_glib_none().0)) }
148    }
149
150    /// Returns the event sequence to which the event belongs.
151    ///
152    /// Related touch events are connected in a sequence. Other
153    /// events typically don't have event sequence information.
154    ///
155    /// # Returns
156    ///
157    /// the event sequence that the event belongs to
158    #[doc(alias = "gdk_event_get_event_sequence")]
159    #[doc(alias = "get_event_sequence")]
160    pub fn event_sequence(&self) -> EventSequence {
161        unsafe {
162            from_glib_none(ffi::gdk_event_get_event_sequence(
163                self.as_ref().to_glib_none().0,
164            ))
165        }
166    }
167
168    /// Retrieves the type of the event.
169    ///
170    /// # Returns
171    ///
172    /// a [`Event`][crate::Event]Type
173    #[doc(alias = "gdk_event_get_event_type")]
174    #[doc(alias = "get_event_type")]
175    pub fn event_type(&self) -> EventType {
176        unsafe {
177            from_glib(ffi::gdk_event_get_event_type(
178                self.as_ref().to_glib_none().0,
179            ))
180        }
181    }
182
183    /// Retrieves the history of the device that @self is for, as a list of
184    /// time and coordinates.
185    ///
186    /// The history includes positions that are not delivered as separate events
187    /// to the application because they occurred in the same frame as @self.
188    ///
189    /// Note that only motion and scroll events record history, and motion
190    /// events do it only if one of the mouse buttons is down, or the device
191    /// has a tool.
192    ///
193    /// # Returns
194    ///
195    /// an
196    ///   array of time and coordinates
197    #[doc(alias = "gdk_event_get_history")]
198    #[doc(alias = "get_history")]
199    pub fn history(&self) -> Vec<TimeCoord> {
200        unsafe {
201            let mut out_n_coords = std::mem::MaybeUninit::uninit();
202            let ret = FromGlibContainer::from_glib_container_num(
203                ffi::gdk_event_get_history(
204                    self.as_ref().to_glib_none().0,
205                    out_n_coords.as_mut_ptr(),
206                ),
207                out_n_coords.assume_init() as _,
208            );
209            ret
210        }
211    }
212
213    /// Returns the modifier state field of an event.
214    ///
215    /// # Returns
216    ///
217    /// the modifier state of @self
218    #[doc(alias = "gdk_event_get_modifier_state")]
219    #[doc(alias = "get_modifier_state")]
220    pub fn modifier_state(&self) -> ModifierType {
221        unsafe {
222            from_glib(ffi::gdk_event_get_modifier_state(
223                self.as_ref().to_glib_none().0,
224            ))
225        }
226    }
227
228    /// Returns whether this event is an 'emulated' pointer event.
229    ///
230    /// Emulated pointer events typically originate from a touch events.
231    ///
232    /// # Returns
233    ///
234    /// [`true`] if this event is emulated
235    #[doc(alias = "gdk_event_get_pointer_emulated")]
236    #[doc(alias = "get_pointer_emulated")]
237    pub fn is_pointer_emulated(&self) -> bool {
238        unsafe {
239            from_glib(ffi::gdk_event_get_pointer_emulated(
240                self.as_ref().to_glib_none().0,
241            ))
242        }
243    }
244
245    /// Extract the event surface relative x/y coordinates from an event.
246    ///
247    /// This position is in [surface coordinates](coordinates.html).
248    ///
249    /// # Returns
250    ///
251    /// whether the positions were set
252    ///
253    /// ## `x`
254    /// location to put event surface x coordinate
255    ///
256    /// ## `y`
257    /// location to put event surface y coordinate
258    #[doc(alias = "gdk_event_get_position")]
259    #[doc(alias = "get_position")]
260    pub fn position(&self) -> Option<(f64, f64)> {
261        unsafe {
262            let mut x = std::mem::MaybeUninit::uninit();
263            let mut y = std::mem::MaybeUninit::uninit();
264            let ret = from_glib(ffi::gdk_event_get_position(
265                self.as_ref().to_glib_none().0,
266                x.as_mut_ptr(),
267                y.as_mut_ptr(),
268            ));
269            if ret {
270                Some((x.assume_init(), y.assume_init()))
271            } else {
272                None
273            }
274        }
275    }
276
277    /// Returns the seat that originated the event.
278    ///
279    /// # Returns
280    ///
281    /// a [`Seat`][crate::Seat].
282    #[doc(alias = "gdk_event_get_seat")]
283    #[doc(alias = "get_seat")]
284    pub fn seat(&self) -> Option<Seat> {
285        unsafe { from_glib_none(ffi::gdk_event_get_seat(self.as_ref().to_glib_none().0)) }
286    }
287
288    /// Extracts the surface associated with an event.
289    ///
290    /// # Returns
291    ///
292    /// The [`Surface`][crate::Surface] associated with the event
293    #[doc(alias = "gdk_event_get_surface")]
294    #[doc(alias = "get_surface")]
295    pub fn surface(&self) -> Option<Surface> {
296        unsafe { from_glib_none(ffi::gdk_event_get_surface(self.as_ref().to_glib_none().0)) }
297    }
298
299    /// Returns the timestamp of @self.
300    ///
301    /// Not all events have timestamps. In that case, this function
302    /// returns `GDK_CURRENT_TIME`.
303    ///
304    /// # Returns
305    ///
306    /// timestamp field from @self
307    #[doc(alias = "gdk_event_get_time")]
308    #[doc(alias = "get_time")]
309    pub fn time(&self) -> u32 {
310        unsafe { ffi::gdk_event_get_time(self.as_ref().to_glib_none().0) }
311    }
312
313    /// Returns whether a [`Event`][crate::Event] should trigger a context menu,
314    /// according to platform conventions.
315    ///
316    /// The right mouse button typically triggers context menus.
317    /// On macOS, Control+left mouse button also triggers.
318    ///
319    /// This function should always be used instead of simply checking for
320    ///
321    /// **⚠️ The following code is in c ⚠️**
322    ///
323    /// ```c
324    /// event->button == GDK_BUTTON_SECONDARY
325    /// ```
326    ///
327    /// # Returns
328    ///
329    /// [`true`] if the event should trigger a context menu.
330    #[doc(alias = "gdk_event_triggers_context_menu")]
331    pub fn triggers_context_menu(&self) -> bool {
332        unsafe {
333            from_glib(ffi::gdk_event_triggers_context_menu(
334                self.as_ref().to_glib_none().0,
335            ))
336        }
337    }
338}