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}