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