gdk/auto/

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

glib::wrapper! {
    /// In addition to a single pointer and keyboard for user interface input,
    /// GDK contains support for a variety of input devices, including graphics
    /// tablets, touchscreens and multiple pointers/keyboards interacting
    /// simultaneously with the user interface. Such input devices often have
    /// additional features, such as sub-pixel positioning information and
    /// additional device-dependent information.
    ///
    /// In order to query the device hierarchy and be aware of changes in the
    /// device hierarchy (such as virtual devices being created or removed, or
    /// physical devices being plugged or unplugged), GDK provides
    /// [`DeviceManager`][crate::DeviceManager].
    ///
    /// By default, and if the platform supports it, GDK is aware of multiple
    /// keyboard/pointer pairs and multitouch devices. This behavior can be
    /// changed by calling `gdk_disable_multidevice()` before [`Display::open()`][crate::Display::open()].
    /// There should rarely be a need to do that though, since GDK defaults
    /// to a compatibility mode in which it will emit just one enter/leave
    /// event pair for all devices on a window. To enable per-device
    /// enter/leave events and other multi-pointer interaction features,
    /// [`Window::set_support_multidevice()`][crate::Window::set_support_multidevice()] must be called on
    /// `GdkWindows` (or `gtk_widget_set_support_multidevice()` on widgets).
    /// window. See the [`Window::set_support_multidevice()`][crate::Window::set_support_multidevice()] documentation
    /// for more information.
    ///
    /// On X11, multi-device support is implemented through XInput 2.
    /// Unless `gdk_disable_multidevice()` is called, the XInput 2
    /// [`DeviceManager`][crate::DeviceManager] implementation will be used as the input source.
    /// Otherwise either the core or XInput 1 implementations will be used.
    ///
    /// For simple applications that don’t have any special interest in
    /// input devices, the so-called “client pointer”
    /// provides a reasonable approximation to a simple setup with a single
    /// pointer and keyboard. The device that has been set as the client
    /// pointer can be accessed via `gdk_device_manager_get_client_pointer()`.
    ///
    /// Conceptually, in multidevice mode there are 2 device types. Virtual
    /// devices (or master devices) are represented by the pointer cursors
    /// and keyboard foci that are seen on the screen. Physical devices (or
    /// slave devices) represent the hardware that is controlling the virtual
    /// devices, and thus have no visible cursor on the screen.
    ///
    /// Virtual devices are always paired, so there is a keyboard device for every
    /// pointer device. Associations between devices may be inspected through
    /// [`DeviceExt::associated_device()`][crate::prelude::DeviceExt::associated_device()].
    ///
    /// There may be several virtual devices, and several physical devices could
    /// be controlling each of these virtual devices. Physical devices may also
    /// be “floating”, which means they are not attached to any virtual device.
    ///
    /// # Master and slave devices
    ///
    ///
    /// ```text
    /// carlos@sacarino:~$ xinput list
    /// ⎡ Virtual core pointer                          id=2    [master pointer  (3)]
    /// ⎜   ↳ Virtual core XTEST pointer                id=4    [slave  pointer  (2)]
    /// ⎜   ↳ Wacom ISDv4 E6 Pen stylus                 id=10   [slave  pointer  (2)]
    /// ⎜   ↳ Wacom ISDv4 E6 Finger touch               id=11   [slave  pointer  (2)]
    /// ⎜   ↳ SynPS/2 Synaptics TouchPad                id=13   [slave  pointer  (2)]
    /// ⎜   ↳ TPPS/2 IBM TrackPoint                     id=14   [slave  pointer  (2)]
    /// ⎜   ↳ Wacom ISDv4 E6 Pen eraser                 id=16   [slave  pointer  (2)]
    /// ⎣ Virtual core keyboard                         id=3    [master keyboard (2)]
    ///     ↳ Virtual core XTEST keyboard               id=5    [slave  keyboard (3)]
    ///     ↳ Power Button                              id=6    [slave  keyboard (3)]
    ///     ↳ Video Bus                                 id=7    [slave  keyboard (3)]
    ///     ↳ Sleep Button                              id=8    [slave  keyboard (3)]
    ///     ↳ Integrated Camera                         id=9    [slave  keyboard (3)]
    ///     ↳ AT Translated Set 2 keyboard              id=12   [slave  keyboard (3)]
    ///     ↳ ThinkPad Extra Buttons                    id=15   [slave  keyboard (3)]
    /// ```
    ///
    /// By default, GDK will automatically listen for events coming from all
    /// master devices, setting the [`Device`][crate::Device] for all events coming from input
    /// devices. Events containing device information are [`EventType::MotionNotify`][crate::EventType::MotionNotify],
    /// [`EventType::ButtonPress`][crate::EventType::ButtonPress], [`EventType::_2buttonPress`][crate::EventType::_2buttonPress], [`EventType::_3buttonPress`][crate::EventType::_3buttonPress],
    /// [`EventType::ButtonRelease`][crate::EventType::ButtonRelease], [`EventType::Scroll`][crate::EventType::Scroll], [`EventType::KeyPress`][crate::EventType::KeyPress], [`EventType::KeyRelease`][crate::EventType::KeyRelease],
    /// [`EventType::EnterNotify`][crate::EventType::EnterNotify], [`EventType::LeaveNotify`][crate::EventType::LeaveNotify], [`EventType::FocusChange`][crate::EventType::FocusChange],
    /// [`EventType::ProximityIn`][crate::EventType::ProximityIn], [`EventType::ProximityOut`][crate::EventType::ProximityOut], [`EventType::DragEnter`][crate::EventType::DragEnter], [`EventType::DragLeave`][crate::EventType::DragLeave],
    /// [`EventType::DragMotion`][crate::EventType::DragMotion], [`EventType::DragStatus`][crate::EventType::DragStatus], [`EventType::DropStart`][crate::EventType::DropStart], [`EventType::DropFinished`][crate::EventType::DropFinished]
    /// and [`EventType::GrabBroken`][crate::EventType::GrabBroken]. When dealing with an event on a master device,
    /// it is possible to get the source (slave) device that the event originated
    /// from via `gdk_event_get_source_device()`.
    ///
    /// On a standard session, all physical devices are connected by default to
    /// the "Virtual Core Pointer/Keyboard" master devices, hence routing all events
    /// through these. This behavior is only modified by device grabs, where the
    /// slave device is temporarily detached for as long as the grab is held, and
    /// more permanently by user modifications to the device hierarchy.
    ///
    /// On certain application specific setups, it may make sense
    /// to detach a physical device from its master pointer, and mapping it to
    /// an specific window. This can be achieved by the combination of
    /// `gdk_device_grab()` and [`DeviceExt::set_mode()`][crate::prelude::DeviceExt::set_mode()].
    ///
    /// In order to listen for events coming from devices
    /// other than a virtual device, [`Window::set_device_events()`][crate::Window::set_device_events()] must be
    /// called. Generally, this function can be used to modify the event mask
    /// for any given device.
    ///
    /// Input devices may also provide additional information besides X/Y.
    /// For example, graphics tablets may also provide pressure and X/Y tilt
    /// information. This information is device-dependent, and may be
    /// queried through `gdk_device_get_axis()`. In multidevice mode, virtual
    /// devices will change axes in order to always represent the physical
    /// device that is routing events through it. Whenever the physical device
    /// changes, the [`n-axes`][struct@crate::Device#n-axes] property will be notified, and
    /// [`DeviceExt::list_axes()`][crate::prelude::DeviceExt::list_axes()] will return the new device axes.
    ///
    /// Devices may also have associated “keys” or
    /// macro buttons. Such keys can be globally set to map into normal X
    /// keyboard events. The mapping is set using [`DeviceExt::set_key()`][crate::prelude::DeviceExt::set_key()].
    ///
    /// In GTK+ 3.20, a new [`Seat`][crate::Seat] object has been introduced that
    /// supersedes [`DeviceManager`][crate::DeviceManager] and should be preferred in newly
    /// written code.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `display`
    ///  Readable | Writeable | Construct Only
    ///
    /// ## Signals
    ///
    ///
    /// #### `device-added`
    ///  The ::device-added signal is emitted either when a new master
    /// pointer is created, or when a slave (Hardware) input device
    /// is plugged in.
    ///
    ///
    ///
    ///
    /// #### `device-changed`
    ///  The ::device-changed signal is emitted whenever a device
    /// has changed in the hierarchy, either slave devices being
    /// disconnected from their master device or connected to
    /// another one, or master devices being added or removed
    /// a slave device.
    ///
    /// If a slave device is detached from all master devices
    /// ([`DeviceExt::associated_device()`][crate::prelude::DeviceExt::associated_device()] returns [`None`]), its
    /// [`DeviceType`][crate::DeviceType] will change to [`DeviceType::Floating`][crate::DeviceType::Floating],
    /// if it's attached, it will change to [`DeviceType::Slave`][crate::DeviceType::Slave].
    ///
    ///
    ///
    ///
    /// #### `device-removed`
    ///  The ::device-removed signal is emitted either when a master
    /// pointer is removed, or when a slave (Hardware) input device
    /// is unplugged.
    ///
    ///
    #[doc(alias = "GdkDeviceManager")]
    pub struct DeviceManager(Object<ffi::GdkDeviceManager>);

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

impl DeviceManager {
    /// Gets the [`Display`][crate::Display] associated to `self`.
    ///
    /// # Returns
    ///
    /// the [`Display`][crate::Display] to which
    ///  `self` is associated to, or [`None`]. This memory is
    ///  owned by GDK and must not be freed or unreferenced.
    #[doc(alias = "gdk_device_manager_get_display")]
    #[doc(alias = "get_display")]
    pub fn display(&self) -> Option<Display> {
        unsafe { from_glib_none(ffi::gdk_device_manager_get_display(self.to_glib_none().0)) }
    }

    /// The ::device-added signal is emitted either when a new master
    /// pointer is created, or when a slave (Hardware) input device
    /// is plugged in.
    /// ## `device`
    /// the newly added [`Device`][crate::Device].
    #[doc(alias = "device-added")]
    pub fn connect_device_added<F: Fn(&Self, &Device) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn device_added_trampoline<F: Fn(&DeviceManager, &Device) + 'static>(
            this: *mut ffi::GdkDeviceManager,
            device: *mut ffi::GdkDevice,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this), &from_glib_borrow(device))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"device-added\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    device_added_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// The ::device-changed signal is emitted whenever a device
    /// has changed in the hierarchy, either slave devices being
    /// disconnected from their master device or connected to
    /// another one, or master devices being added or removed
    /// a slave device.
    ///
    /// If a slave device is detached from all master devices
    /// ([`DeviceExt::associated_device()`][crate::prelude::DeviceExt::associated_device()] returns [`None`]), its
    /// [`DeviceType`][crate::DeviceType] will change to [`DeviceType::Floating`][crate::DeviceType::Floating],
    /// if it's attached, it will change to [`DeviceType::Slave`][crate::DeviceType::Slave].
    /// ## `device`
    /// the [`Device`][crate::Device] that changed.
    #[doc(alias = "device-changed")]
    pub fn connect_device_changed<F: Fn(&Self, &Device) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn device_changed_trampoline<F: Fn(&DeviceManager, &Device) + 'static>(
            this: *mut ffi::GdkDeviceManager,
            device: *mut ffi::GdkDevice,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this), &from_glib_borrow(device))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"device-changed\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    device_changed_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// The ::device-removed signal is emitted either when a master
    /// pointer is removed, or when a slave (Hardware) input device
    /// is unplugged.
    /// ## `device`
    /// the just removed [`Device`][crate::Device].
    #[doc(alias = "device-removed")]
    pub fn connect_device_removed<F: Fn(&Self, &Device) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn device_removed_trampoline<F: Fn(&DeviceManager, &Device) + 'static>(
            this: *mut ffi::GdkDeviceManager,
            device: *mut ffi::GdkDevice,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this), &from_glib_borrow(device))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"device-removed\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    device_removed_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

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