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}