gdk4/auto/

event.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{
    ffi, AxisUse, Device, DeviceTool, Display, EventSequence, EventType, ModifierType, Seat,
    Surface, TimeCoord,
};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// [`Event`][crate::Event]s are immutable data structures, created by GDK to
    /// represent windowing system events.
    ///
    /// In GTK applications the events are handled automatically by toplevel
    /// widgets and passed on to the event controllers of appropriate widgets,
    /// so using [`Event`][crate::Event] and its related API is rarely needed.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    #[doc(alias = "GdkEvent")]
    pub struct Event(Shared<ffi::GdkEvent>);

    match fn {
        ref => |ptr| ffi::gdk_event_ref(ptr),
        unref => |ptr| ffi::gdk_event_unref(ptr),
    }
}

impl StaticType for Event {
    fn static_type() -> glib::Type {
        unsafe { from_glib(ffi::gdk_event_get_type()) }
    }
}

impl Event {
    pub const NONE: Option<&'static Event> = None;

    /// Extracts all axis values from an event.
    ///
    /// To find out which axes are used, use [`DeviceTool::axes()`][crate::DeviceTool::axes()]
    /// on the device tool returned by [`device_tool()`][Self::device_tool()].
    ///
    /// # Returns
    ///
    /// [`true`] on success, otherwise [`false`]
    ///
    /// ## `axes`
    /// the array of values for all axes
    #[doc(alias = "gdk_event_get_axes")]
    #[doc(alias = "get_axes")]
    pub fn axes(&self) -> Option<Vec<f64>> {
        unsafe {
            let mut axes = std::ptr::null_mut();
            let mut n_axes = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gdk_event_get_axes(
                self.as_ref().to_glib_none().0,
                &mut axes,
                n_axes.as_mut_ptr(),
            ));
            if ret {
                Some(FromGlibContainer::from_glib_none_num(
                    axes,
                    n_axes.assume_init() as _,
                ))
            } else {
                None
            }
        }
    }

    /// Extract the axis value for a particular axis use from
    /// an event structure.
    ///
    /// To find out which axes are used, use [`DeviceTool::axes()`][crate::DeviceTool::axes()]
    /// on the device tool returned by [`device_tool()`][Self::device_tool()].
    /// ## `axis_use`
    /// the axis use to look for
    ///
    /// # Returns
    ///
    /// [`true`] if the specified axis was found, otherwise [`false`]
    ///
    /// ## `value`
    /// location to store the value found
    #[doc(alias = "gdk_event_get_axis")]
    #[doc(alias = "get_axis")]
    pub fn axis(&self, axis_use: AxisUse) -> Option<f64> {
        unsafe {
            let mut value = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gdk_event_get_axis(
                self.as_ref().to_glib_none().0,
                axis_use.into_glib(),
                value.as_mut_ptr(),
            ));
            if ret {
                Some(value.assume_init())
            } else {
                None
            }
        }
    }

    /// Returns the device of an event.
    ///
    /// # Returns
    ///
    /// a [`Device`][crate::Device]
    #[doc(alias = "gdk_event_get_device")]
    #[doc(alias = "get_device")]
    pub fn device(&self) -> Option<Device> {
        unsafe { from_glib_none(ffi::gdk_event_get_device(self.as_ref().to_glib_none().0)) }
    }

    /// Returns a [`DeviceTool`][crate::DeviceTool] representing the tool that
    /// caused the event.
    ///
    /// If the was not generated by a device that supports
    /// different tools (such as a tablet), this function will
    /// return [`None`].
    ///
    /// Note: the [`DeviceTool`][crate::DeviceTool] will be constant during
    /// the application lifetime, if settings must be stored
    /// persistently across runs, see [`DeviceTool::serial()`][crate::DeviceTool::serial()].
    ///
    /// # Returns
    ///
    /// The current device tool
    #[doc(alias = "gdk_event_get_device_tool")]
    #[doc(alias = "get_device_tool")]
    pub fn device_tool(&self) -> Option<DeviceTool> {
        unsafe {
            from_glib_none(ffi::gdk_event_get_device_tool(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Retrieves the display associated to the @self.
    ///
    /// # Returns
    ///
    /// a [`Display`][crate::Display]
    #[doc(alias = "gdk_event_get_display")]
    #[doc(alias = "get_display")]
    pub fn display(&self) -> Option<Display> {
        unsafe { from_glib_none(ffi::gdk_event_get_display(self.as_ref().to_glib_none().0)) }
    }

    /// Returns the event sequence to which the event belongs.
    ///
    /// Related touch events are connected in a sequence. Other
    /// events typically don't have event sequence information.
    ///
    /// # Returns
    ///
    /// the event sequence that the event belongs to
    #[doc(alias = "gdk_event_get_event_sequence")]
    #[doc(alias = "get_event_sequence")]
    pub fn event_sequence(&self) -> EventSequence {
        unsafe {
            from_glib_none(ffi::gdk_event_get_event_sequence(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Retrieves the type of the event.
    ///
    /// # Returns
    ///
    /// a [`Event`][crate::Event]Type
    #[doc(alias = "gdk_event_get_event_type")]
    #[doc(alias = "get_event_type")]
    pub fn event_type(&self) -> EventType {
        unsafe {
            from_glib(ffi::gdk_event_get_event_type(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Retrieves the history of the device that @self is for, as a list of
    /// time and coordinates.
    ///
    /// The history includes positions that are not delivered as separate events
    /// to the application because they occurred in the same frame as @self.
    ///
    /// Note that only motion and scroll events record history, and motion
    /// events do it only if one of the mouse buttons is down, or the device
    /// has a tool.
    ///
    /// # Returns
    ///
    /// an
    ///   array of time and coordinates
    #[doc(alias = "gdk_event_get_history")]
    #[doc(alias = "get_history")]
    pub fn history(&self) -> Vec<TimeCoord> {
        unsafe {
            let mut out_n_coords = std::mem::MaybeUninit::uninit();
            let ret = FromGlibContainer::from_glib_container_num(
                ffi::gdk_event_get_history(
                    self.as_ref().to_glib_none().0,
                    out_n_coords.as_mut_ptr(),
                ),
                out_n_coords.assume_init() as _,
            );
            ret
        }
    }

    /// Returns the modifier state field of an event.
    ///
    /// # Returns
    ///
    /// the modifier state of @self
    #[doc(alias = "gdk_event_get_modifier_state")]
    #[doc(alias = "get_modifier_state")]
    pub fn modifier_state(&self) -> ModifierType {
        unsafe {
            from_glib(ffi::gdk_event_get_modifier_state(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Returns whether this event is an 'emulated' pointer event.
    ///
    /// Emulated pointer events typically originate from a touch events.
    ///
    /// # Returns
    ///
    /// [`true`] if this event is emulated
    #[doc(alias = "gdk_event_get_pointer_emulated")]
    #[doc(alias = "get_pointer_emulated")]
    pub fn is_pointer_emulated(&self) -> bool {
        unsafe {
            from_glib(ffi::gdk_event_get_pointer_emulated(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Extract the event surface relative x/y coordinates from an event.
    ///
    /// This position is in [surface coordinates](coordinates.html).
    ///
    /// # Returns
    ///
    /// whether the positions were set
    ///
    /// ## `x`
    /// location to put event surface x coordinate
    ///
    /// ## `y`
    /// location to put event surface y coordinate
    #[doc(alias = "gdk_event_get_position")]
    #[doc(alias = "get_position")]
    pub fn position(&self) -> Option<(f64, f64)> {
        unsafe {
            let mut x = std::mem::MaybeUninit::uninit();
            let mut y = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gdk_event_get_position(
                self.as_ref().to_glib_none().0,
                x.as_mut_ptr(),
                y.as_mut_ptr(),
            ));
            if ret {
                Some((x.assume_init(), y.assume_init()))
            } else {
                None
            }
        }
    }

    /// Returns the seat that originated the event.
    ///
    /// # Returns
    ///
    /// a [`Seat`][crate::Seat].
    #[doc(alias = "gdk_event_get_seat")]
    #[doc(alias = "get_seat")]
    pub fn seat(&self) -> Option<Seat> {
        unsafe { from_glib_none(ffi::gdk_event_get_seat(self.as_ref().to_glib_none().0)) }
    }

    /// Extracts the surface associated with an event.
    ///
    /// # Returns
    ///
    /// The [`Surface`][crate::Surface] associated with the event
    #[doc(alias = "gdk_event_get_surface")]
    #[doc(alias = "get_surface")]
    pub fn surface(&self) -> Option<Surface> {
        unsafe { from_glib_none(ffi::gdk_event_get_surface(self.as_ref().to_glib_none().0)) }
    }

    /// Returns the timestamp of @self.
    ///
    /// Not all events have timestamps. In that case, this function
    /// returns `GDK_CURRENT_TIME`.
    ///
    /// # Returns
    ///
    /// timestamp field from @self
    #[doc(alias = "gdk_event_get_time")]
    #[doc(alias = "get_time")]
    pub fn time(&self) -> u32 {
        unsafe { ffi::gdk_event_get_time(self.as_ref().to_glib_none().0) }
    }

    /// Returns whether a [`Event`][crate::Event] should trigger a context menu,
    /// according to platform conventions.
    ///
    /// The right mouse button typically triggers context menus.
    /// On macOS, Control+left mouse button also triggers.
    ///
    /// This function should always be used instead of simply checking for
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// event->button == GDK_BUTTON_SECONDARY
    /// ```
    ///
    /// # Returns
    ///
    /// [`true`] if the event should trigger a context menu.
    #[doc(alias = "gdk_event_triggers_context_menu")]
    pub fn triggers_context_menu(&self) -> bool {
        unsafe {
            from_glib(ffi::gdk_event_triggers_context_menu(
                self.as_ref().to_glib_none().0,
            ))
        }
    }
}