gdk/auto/

keymap.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::{Display, ModifierIntent, ModifierType};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::{boxed::Box as Box_, fmt, mem, mem::transmute};

glib::wrapper! {
    /// A [`Keymap`][crate::Keymap] defines the translation from keyboard state
    /// (including a hardware key, a modifier mask, and active keyboard group)
    /// to a keyval. This translation has two phases. The first phase is
    /// to determine the effective keyboard group and level for the keyboard
    /// state; the second phase is to look up the keycode/group/level triplet
    /// in the keymap and see what keyval it corresponds to.
    ///
    /// ## Signals
    ///
    ///
    /// #### `direction-changed`
    ///  The ::direction-changed signal gets emitted when the direction of
    /// the keymap changes.
    ///
    ///
    ///
    ///
    /// #### `keys-changed`
    ///  The ::keys-changed signal is emitted when the mapping represented by
    /// `keymap` changes.
    ///
    ///
    ///
    ///
    /// #### `state-changed`
    ///  The ::state-changed signal is emitted when the state of the
    /// keyboard changes, e.g when Caps Lock is turned on or off.
    /// See [`Keymap::is_caps_locked()`][crate::Keymap::is_caps_locked()].
    ///
    ///
    #[doc(alias = "GdkKeymap")]
    pub struct Keymap(Object<ffi::GdkKeymap>);

    match fn {
        type_ => || ffi::gdk_keymap_get_type(),
    }
}

impl Keymap {
    /// Returns whether the Caps Lock modifer is locked.
    ///
    /// # Returns
    ///
    /// [`true`] if Caps Lock is on
    #[doc(alias = "gdk_keymap_get_caps_lock_state")]
    #[doc(alias = "get_caps_lock_state")]
    pub fn is_caps_locked(&self) -> bool {
        unsafe { from_glib(ffi::gdk_keymap_get_caps_lock_state(self.to_glib_none().0)) }
    }

    /// Returns the direction of effective layout of the keymap.
    ///
    /// # Returns
    ///
    /// [`pango::Direction::Ltr`][crate::pango::Direction::Ltr] or [`pango::Direction::Rtl`][crate::pango::Direction::Rtl]
    ///  if it can determine the direction. [`pango::Direction::Neutral`][crate::pango::Direction::Neutral]
    ///  otherwise.
    #[doc(alias = "gdk_keymap_get_direction")]
    #[doc(alias = "get_direction")]
    pub fn direction(&self) -> pango::Direction {
        unsafe { from_glib(ffi::gdk_keymap_get_direction(self.to_glib_none().0)) }
    }

    /// Returns the modifier mask the `self`’s windowing system backend
    /// uses for a particular purpose.
    ///
    /// Note that this function always returns real hardware modifiers, not
    /// virtual ones (e.g. it will return [`ModifierType::MOD1_MASK`][crate::ModifierType::MOD1_MASK] rather than
    /// [`ModifierType::META_MASK`][crate::ModifierType::META_MASK] if the backend maps MOD1 to META), so there are use
    /// cases where the return value of this function has to be transformed
    /// by [`add_virtual_modifiers()`][Self::add_virtual_modifiers()] in order to contain the
    /// expected result.
    /// ## `intent`
    /// the use case for the modifier mask
    ///
    /// # Returns
    ///
    /// the modifier mask used for `intent`.
    #[doc(alias = "gdk_keymap_get_modifier_mask")]
    #[doc(alias = "get_modifier_mask")]
    pub fn modifier_mask(&self, intent: ModifierIntent) -> ModifierType {
        unsafe {
            from_glib(ffi::gdk_keymap_get_modifier_mask(
                self.to_glib_none().0,
                intent.into_glib(),
            ))
        }
    }

    /// Returns the current modifier state.
    ///
    /// # Returns
    ///
    /// the current modifier state.
    #[doc(alias = "gdk_keymap_get_modifier_state")]
    #[doc(alias = "get_modifier_state")]
    pub fn modifier_state(&self) -> u32 {
        unsafe { ffi::gdk_keymap_get_modifier_state(self.to_glib_none().0) }
    }

    /// Returns whether the Num Lock modifer is locked.
    ///
    /// # Returns
    ///
    /// [`true`] if Num Lock is on
    #[doc(alias = "gdk_keymap_get_num_lock_state")]
    #[doc(alias = "get_num_lock_state")]
    pub fn is_num_locked(&self) -> bool {
        unsafe { from_glib(ffi::gdk_keymap_get_num_lock_state(self.to_glib_none().0)) }
    }

    /// Returns whether the Scroll Lock modifer is locked.
    ///
    /// # Returns
    ///
    /// [`true`] if Scroll Lock is on
    #[doc(alias = "gdk_keymap_get_scroll_lock_state")]
    #[doc(alias = "get_scroll_lock_state")]
    pub fn is_scroll_locked(&self) -> bool {
        unsafe { from_glib(ffi::gdk_keymap_get_scroll_lock_state(self.to_glib_none().0)) }
    }

    /// Determines if keyboard layouts for both right-to-left and left-to-right
    /// languages are in use.
    ///
    /// # Returns
    ///
    /// [`true`] if there are layouts in both directions, [`false`] otherwise
    #[doc(alias = "gdk_keymap_have_bidi_layouts")]
    pub fn have_bidi_layouts(&self) -> bool {
        unsafe { from_glib(ffi::gdk_keymap_have_bidi_layouts(self.to_glib_none().0)) }
    }

    /// Translates the contents of a [`EventKey`][crate::EventKey] into a keyval, effective
    /// group, and level. Modifiers that affected the translation and
    /// are thus unavailable for application use are returned in
    /// `consumed_modifiers`.
    /// See [Groups][key-group-explanation] for an explanation of
    /// groups and levels. 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`. For convenience, [`EventKey`][crate::EventKey] already contains the translated
    /// keyval, so this function isn’t as useful as you might think.
    ///
    /// `consumed_modifiers` gives modifiers that should be masked outfrom `state`
    /// when comparing this key press to a hot key. 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.
    ///
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    /// // We want to ignore irrelevant modifiers like ScrollLock
    /// #define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK)
    /// gdk_keymap_translate_keyboard_state (keymap, event->hardware_keycode,
    ///                                      event->state, event->group,
    ///                                      &keyval, NULL, NULL, &consumed);
    /// if (keyval == GDK_PLUS &&
    ///     (event->state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
    ///   // Control was pressed
    /// ```
    ///
    /// An older interpretation `consumed_modifiers` was that it contained
    /// all modifiers that might affect the translation of the key;
    /// this allowed accelerators to be stored with irrelevant consumed
    /// modifiers, by doing:
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    /// // XXX Don’t do this XXX
    /// if (keyval == accel_keyval &&
    ///     (event->state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
    ///   // Accelerator was pressed
    /// ```
    ///
    /// However, this did not work if multi-modifier combinations were
    /// used in the keymap, since, for instance, ``<Control>`` would be
    /// masked out even if only ``<Control>``<Alt>`` was used in the keymap.
    /// To support this usage as well as well as possible, all single
    /// modifier combinations that could affect the key for any combination
    /// of modifiers will be returned in `consumed_modifiers`; multi-modifier
    /// combinations are returned only when actually found in `state`. When
    /// you store accelerators, you should always store them with consumed
    /// modifiers removed. Store ``<Control>`plus`, not ``<Control>``<Shift>`plus`,
    /// ## `hardware_keycode`
    /// a keycode
    /// ## `state`
    /// a modifier state
    /// ## `group`
    /// active keyboard group
    ///
    /// # Returns
    ///
    /// [`true`] if there was a keyval bound to the keycode/state/group
    ///
    /// ## `keyval`
    /// return location for keyval, or [`None`]
    ///
    /// ## `effective_group`
    /// return location for effective
    ///  group, or [`None`]
    ///
    /// ## `level`
    /// return location for level, or [`None`]
    ///
    /// ## `consumed_modifiers`
    /// return location for modifiers
    ///  that were used to determine the group or level, or [`None`]
    #[doc(alias = "gdk_keymap_translate_keyboard_state")]
    pub fn translate_keyboard_state(
        &self,
        hardware_keycode: u32,
        state: ModifierType,
        group: i32,
    ) -> Option<(u32, i32, i32, ModifierType)> {
        unsafe {
            let mut keyval = mem::MaybeUninit::uninit();
            let mut effective_group = mem::MaybeUninit::uninit();
            let mut level = mem::MaybeUninit::uninit();
            let mut consumed_modifiers = mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gdk_keymap_translate_keyboard_state(
                self.to_glib_none().0,
                hardware_keycode,
                state.into_glib(),
                group,
                keyval.as_mut_ptr(),
                effective_group.as_mut_ptr(),
                level.as_mut_ptr(),
                consumed_modifiers.as_mut_ptr(),
            ));
            if ret {
                Some((
                    keyval.assume_init(),
                    effective_group.assume_init(),
                    level.assume_init(),
                    from_glib(consumed_modifiers.assume_init()),
                ))
            } else {
                None
            }
        }
    }

    /// Returns the [`Keymap`][crate::Keymap] attached to `display`.
    /// ## `display`
    /// the [`Display`][crate::Display].
    ///
    /// # Returns
    ///
    /// the [`Keymap`][crate::Keymap] attached to `display`.
    #[doc(alias = "gdk_keymap_get_for_display")]
    #[doc(alias = "get_for_display")]
    pub fn for_display(display: &Display) -> Option<Keymap> {
        skip_assert_initialized!();
        unsafe { from_glib_none(ffi::gdk_keymap_get_for_display(display.to_glib_none().0)) }
    }

    /// The ::direction-changed signal gets emitted when the direction of
    /// the keymap changes.
    #[doc(alias = "direction-changed")]
    pub fn connect_direction_changed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn direction_changed_trampoline<F: Fn(&Keymap) + 'static>(
            this: *mut ffi::GdkKeymap,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"direction-changed\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    direction_changed_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// The ::keys-changed signal is emitted when the mapping represented by
    /// `keymap` changes.
    #[doc(alias = "keys-changed")]
    pub fn connect_keys_changed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn keys_changed_trampoline<F: Fn(&Keymap) + 'static>(
            this: *mut ffi::GdkKeymap,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"keys-changed\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    keys_changed_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// The ::state-changed signal is emitted when the state of the
    /// keyboard changes, e.g when Caps Lock is turned on or off.
    /// See [`is_caps_locked()`][Self::is_caps_locked()].
    #[doc(alias = "state-changed")]
    pub fn connect_state_changed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn state_changed_trampoline<F: Fn(&Keymap) + 'static>(
            this: *mut ffi::GdkKeymap,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"state-changed\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    state_changed_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl fmt::Display for Keymap {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("Keymap")
    }
}