gdk4/

display.rs

// Take a look at the license at the top of the repository in the LICENSE file.

use glib::translate::*;

use crate::{Display, Key, KeymapKey, ModifierType, ffi, prelude::*};

#[derive(Debug, PartialEq, Eq, Ord, PartialOrd)]
pub enum Backend {
    Wayland,
    X11,
    Win32,
    MacOS,
    Broadway,
}

impl Backend {
    // rustdoc-stripper-ignore-next
    /// Equivalent to the C macro `GDK_IS_WAYLAND_DISPLAY`
    #[doc(alias = "GDK_IS_WAYLAND_DISPLAY")]
    pub fn is_wayland(&self) -> bool {
        matches!(self, Self::Wayland)
    }

    // rustdoc-stripper-ignore-next
    /// Equivalent to the C macro `GDK_IS_X11_DISPLAY`
    #[doc(alias = "GDK_IS_X11_DISPLAY")]
    pub fn is_x11(&self) -> bool {
        matches!(self, Self::X11)
    }

    // rustdoc-stripper-ignore-next
    /// Equivalent to the C macro `GDK_IS_WIN32_DISPLAY`
    #[doc(alias = "GDK_IS_WIN32_DISPLAY")]
    pub fn is_win32(&self) -> bool {
        matches!(self, Self::Win32)
    }

    // rustdoc-stripper-ignore-next
    /// Equivalent to the C macro `GDK_IS_MACOS_DISPLAY`
    #[doc(alias = "GDK_IS_MACOS_DISPLAY")]
    pub fn is_macos(&self) -> bool {
        matches!(self, Self::MacOS)
    }

    // rustdoc-stripper-ignore-next
    /// Equivalent to the C macro `GDK_IS_BROADWAY_DISPLAY`
    #[doc(alias = "GDK_IS_BROADWAY_DISPLAY")]
    pub fn is_broadway(&self) -> bool {
        matches!(self, Self::Broadway)
    }
}

// rustdoc-stripper-ignore-next
/// Trait containing manually implemented methods of
/// [`Display`](crate::Display).
pub trait DisplayExtManual: IsA<Display> + 'static {
    /// Translates the contents of a `GdkEventKey` into a keyval, effective group,
    /// and level.
    ///
    /// Modifiers that affected the translation and are thus unavailable for
    /// application use are returned in @consumed_modifiers.
    ///
    /// The @effective_group is the group that was actually used for the
    /// translation; some keys such as Enter are not affected by the active
    /// keyboard group. The @level is derived from @state.
    ///
    /// @consumed_modifiers gives modifiers that should be masked out
    /// from @state when comparing this key press to a keyboard shortcut.
    /// For instance, on a US keyboard, the `plus` symbol is shifted, so
    /// when comparing a key press to a `<Control>plus` accelerator `<Shift>`
    /// should be masked out.
    ///
    /// This function should rarely be needed, since `GdkEventKey` already
    /// contains the translated keyval. It is exported for the benefit of
    /// virtualized test environments.
    /// ## `keycode`
    /// a keycode
    /// ## `state`
    /// a modifier state
    /// ## `group`
    /// active keyboard group
    ///
    /// # Returns
    ///
    /// [`true`] if there was a keyval bound to keycode/state/group.
    ///
    /// ## `keyval`
    /// return location for keyval
    ///
    /// ## `effective_group`
    /// return location for effective group
    ///
    /// ## `level`
    /// return location for level
    ///
    /// ## `consumed`
    /// return location for modifiers that were used
    ///   to determine the group or level
    #[doc(alias = "gdk_display_translate_key")]
    fn translate_key(
        &self,
        keycode: u32,
        state: ModifierType,
        group: i32,
    ) -> Option<(Key, i32, i32, ModifierType)> {
        unsafe {
            let mut keyval = std::mem::MaybeUninit::uninit();
            let mut effective_group = std::mem::MaybeUninit::uninit();
            let mut level = std::mem::MaybeUninit::uninit();
            let mut consumed = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gdk_display_translate_key(
                self.as_ref().to_glib_none().0,
                keycode,
                state.into_glib(),
                group,
                keyval.as_mut_ptr(),
                effective_group.as_mut_ptr(),
                level.as_mut_ptr(),
                consumed.as_mut_ptr(),
            ));
            if ret {
                let keyval = keyval.assume_init();
                let effective_group = effective_group.assume_init();
                let level = level.assume_init();
                let consumed = consumed.assume_init();
                Some((
                    from_glib(keyval),
                    effective_group,
                    level,
                    from_glib(consumed),
                ))
            } else {
                None
            }
        }
    }

    /// Retrieves a desktop-wide setting such as double-click time
    /// for the @self.
    /// ## `name`
    /// the name of the setting
    /// ## `value`
    /// location to store the value of the setting
    ///
    /// # Returns
    ///
    /// [`true`] if the setting existed and a value was stored
    ///   in @value, [`false`] otherwise
    #[doc(alias = "gdk_display_get_setting")]
    fn get_setting(&self, name: impl IntoGStr) -> Option<glib::Value> {
        unsafe {
            name.run_with_gstr(|name| {
                let mut value = glib::Value::uninitialized();
                let ret = ffi::gdk_display_get_setting(
                    self.as_ref().to_glib_none().0,
                    name.as_ptr(),
                    value.to_glib_none_mut().0,
                );
                if from_glib(ret) { Some(value) } else { None }
            })
        }
    }

    /// Obtains a list of keycode/group/level combinations that will
    /// generate @keyval.
    ///
    /// Groups and levels are two kinds of keyboard mode; in general, the level
    /// determines whether the top or bottom symbol on a key is used, and the
    /// group determines whether the left or right symbol is used.
    ///
    /// On US keyboards, the shift key changes the keyboard level, and there
    /// are no groups. A group switch key might convert a keyboard between
    /// Hebrew to English modes, for example.
    ///
    /// `GdkEventKey` contains a `group` field that indicates the active
    /// keyboard group. The level is computed from the modifier mask.
    ///
    /// The returned array should be freed with g_free().
    /// ## `keyval`
    /// a keyval, such as `GDK_KEY_a`, `GDK_KEY_Up`, `GDK_KEY_Return`, etc.
    ///
    /// # Returns
    ///
    /// [`true`] if keys were found and returned
    ///
    /// ## `keys`
    /// return location
    ///   for an array of [`KeymapKey`][crate::KeymapKey]
    #[doc(alias = "gdk_display_map_keyval")]
    fn map_keyval(&self, keyval: Key) -> Option<Vec<KeymapKey>> {
        unsafe {
            let mut keys = std::ptr::null_mut();
            let mut n_keys = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gdk_display_map_keyval(
                self.as_ref().to_glib_none().0,
                keyval.into_glib(),
                &mut keys,
                n_keys.as_mut_ptr(),
            ));
            if ret {
                Some(FromGlibContainer::from_glib_full_num(
                    keys,
                    n_keys.assume_init() as usize,
                ))
            } else {
                None
            }
        }
    }

    /// Returns the keyvals bound to @keycode.
    ///
    /// The Nth [`KeymapKey`][crate::KeymapKey] in @keys is bound to the Nth keyval in @keyvals.
    ///
    /// When a keycode is pressed by the user, the keyval from
    /// this list of entries is selected by considering the effective
    /// keyboard group and level.
    ///
    /// Free the returned arrays with g_free().
    /// ## `keycode`
    /// a keycode
    ///
    /// # Returns
    ///
    /// [`true`] if there were any entries
    ///
    /// ## `keys`
    /// return
    ///   location for array of [`KeymapKey`][crate::KeymapKey]
    ///
    /// ## `keyvals`
    /// return
    ///   location for array of keyvals
    #[doc(alias = "gdk_display_map_keycode")]
    fn map_keycode(&self, keycode: u32) -> Option<Vec<(KeymapKey, Key)>> {
        unsafe {
            let mut keys = std::ptr::null_mut();
            let mut keyvals = std::ptr::null_mut();
            let mut n_entries = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gdk_display_map_keycode(
                self.as_ref().to_glib_none().0,
                keycode,
                &mut keys,
                &mut keyvals,
                n_entries.as_mut_ptr(),
            ));
            if ret {
                let n_keys = n_entries.assume_init() as usize;
                let keyvals: Vec<u32> = FromGlibContainer::from_glib_full_num(keyvals, n_keys);
                let keyvals = keyvals.into_iter().map(|k| from_glib(k));
                let keys: Vec<KeymapKey> = FromGlibContainer::from_glib_full_num(keys, n_keys);

                Some(keys.into_iter().zip(keyvals).collect())
            } else {
                None
            }
        }
    }

    // rustdoc-stripper-ignore-next
    /// Get the currently used display backend
    fn backend(&self) -> Backend {
        match self.as_ref().type_().name() {
            "GdkWaylandDisplay" => Backend::Wayland,
            "GdkX11Display" => Backend::X11,
            "GdkMacosDisplay" => Backend::MacOS,
            "GdkWin32Display" => Backend::Win32,
            "GdkBroadwayDisplay" => Backend::Broadway,
            e => panic!("Unsupported display backend {e}"),
        }
    }
}

impl<O: IsA<Display>> DisplayExtManual for O {}