gdk4/auto/

cursor.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, Texture};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// [`Cursor`][crate::Cursor] is used to create and destroy cursors.
    ///
    /// Cursors are immutable objects, so once you created them, there is no way
    /// to modify them later. You should create a new cursor when you want to change
    /// something about it.
    ///
    /// Cursors by themselves are not very interesting: they must be bound to a
    /// window for users to see them. This is done with [`SurfaceExt::set_cursor()`][crate::prelude::SurfaceExt::set_cursor()]
    /// or [`SurfaceExt::set_device_cursor()`][crate::prelude::SurfaceExt::set_device_cursor()]. Applications will typically
    /// use higher-level GTK functions such as [gtk_widget_set_cursor()](../gtk4/method.Widget.set_cursor.html)
    /// instead.
    ///
    /// Cursors are not bound to a given [`Display`][crate::Display], so they can be shared.
    /// However, the appearance of cursors may vary when used on different
    /// platforms.
    ///
    /// ## Named and texture cursors
    ///
    /// There are multiple ways to create cursors. The platform's own cursors
    /// can be created with [`from_name()`][Self::from_name()]. That function lists
    /// the commonly available names that are shared with the CSS specification.
    /// Other names may be available, depending on the platform in use. On some
    /// platforms, what images are used for named cursors may be influenced by
    /// the cursor theme.
    ///
    /// Another option to create a cursor is to use [`from_texture()`][Self::from_texture()]
    /// and provide an image to use for the cursor.
    ///
    /// To ease work with unsupported cursors, a fallback cursor can be provided.
    /// If a [`Surface`][crate::Surface] cannot use a cursor because of the reasons mentioned
    /// above, it will try the fallback cursor. Fallback cursors can themselves have
    /// fallback cursors again, so it is possible to provide a chain of progressively
    /// easier to support cursors. If none of the provided cursors can be supported,
    /// the default cursor will be the ultimate fallback.
    ///
    /// ## Properties
    ///
    ///
    /// #### `fallback`
    ///  Cursor to fall back to if this cursor cannot be displayed.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `hotspot-x`
    ///  X position of the cursor hotspot in the cursor image.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `hotspot-y`
    ///  Y position of the cursor hotspot in the cursor image.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `name`
    ///  Name of this this cursor.
    ///
    /// The name will be [`None`] if the cursor was created from a texture.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `texture`
    ///  The texture displayed by this cursor.
    ///
    /// The texture will be [`None`] if the cursor was created from a name.
    ///
    /// Readable | Writeable | Construct Only
    #[doc(alias = "GdkCursor")]
    pub struct Cursor(Object<ffi::GdkCursor>);

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

impl Cursor {
    /// Creates a new cursor by looking up @name in the current cursor
    /// theme.
    ///
    /// A recommended set of cursor names that will work across different
    /// platforms can be found in the CSS specification:
    ///
    /// | | | | |
    /// | --- | --- | ---- | --- |
    /// | "none" | ![](default_cursor.png) "default" | ![](help_cursor.png) "help" | ![](pointer_cursor.png) "pointer" |
    /// | ![](context_menu_cursor.png) "context-menu" | ![](progress_cursor.png) "progress" | ![](wait_cursor.png) "wait" | ![](cell_cursor.png) "cell" |
    /// | ![](crosshair_cursor.png) "crosshair" | ![](text_cursor.png) "text" | ![](vertical_text_cursor.png) "vertical-text" | ![](alias_cursor.png) "alias" |
    /// | ![](copy_cursor.png) "copy" | ![](no_drop_cursor.png) "no-drop" | ![](move_cursor.png) "move" | ![](not_allowed_cursor.png) "not-allowed" |
    /// | ![](grab_cursor.png) "grab" | ![](grabbing_cursor.png) "grabbing" | ![](all_scroll_cursor.png) "all-scroll" | ![](col_resize_cursor.png) "col-resize" |
    /// | ![](row_resize_cursor.png) "row-resize" | ![](n_resize_cursor.png) "n-resize" | ![](e_resize_cursor.png) "e-resize" | ![](s_resize_cursor.png) "s-resize" |
    /// | ![](w_resize_cursor.png) "w-resize" | ![](ne_resize_cursor.png) "ne-resize" | ![](nw_resize_cursor.png) "nw-resize" | ![](sw_resize_cursor.png) "sw-resize" |
    /// | ![](se_resize_cursor.png) "se-resize" | ![](ew_resize_cursor.png) "ew-resize" | ![](ns_resize_cursor.png) "ns-resize" | ![](nesw_resize_cursor.png) "nesw-resize" |
    /// | ![](nwse_resize_cursor.png) "nwse-resize" | ![](zoom_in_cursor.png) "zoom-in" | ![](zoom_out_cursor.png) "zoom-out" | |
    /// ## `name`
    /// the name of the cursor
    /// ## `fallback`
    /// [`None`] or the [`Cursor`][crate::Cursor] to fall back to when
    ///   this one cannot be supported
    ///
    /// # Returns
    ///
    /// a new [`Cursor`][crate::Cursor], or [`None`] if there is no
    ///   cursor with the given name
    #[doc(alias = "gdk_cursor_new_from_name")]
    #[doc(alias = "new_from_name")]
    pub fn from_name(name: &str, fallback: Option<&Cursor>) -> Option<Cursor> {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::gdk_cursor_new_from_name(
                name.to_glib_none().0,
                fallback.to_glib_none().0,
            ))
        }
    }

    /// Creates a new cursor from a [`Texture`][crate::Texture].
    /// ## `texture`
    /// the texture providing the pixel data
    /// ## `hotspot_x`
    /// the horizontal offset of the “hotspot” of the cursor
    /// ## `hotspot_y`
    /// the vertical offset of the “hotspot” of the cursor
    /// ## `fallback`
    /// the [`Cursor`][crate::Cursor] to fall back to when
    ///   this one cannot be supported
    ///
    /// # Returns
    ///
    /// a new [`Cursor`][crate::Cursor]
    #[doc(alias = "gdk_cursor_new_from_texture")]
    #[doc(alias = "new_from_texture")]
    pub fn from_texture(
        texture: &impl IsA<Texture>,
        hotspot_x: i32,
        hotspot_y: i32,
        fallback: Option<&Cursor>,
    ) -> Cursor {
        skip_assert_initialized!();
        unsafe {
            from_glib_full(ffi::gdk_cursor_new_from_texture(
                texture.as_ref().to_glib_none().0,
                hotspot_x,
                hotspot_y,
                fallback.to_glib_none().0,
            ))
        }
    }

    // rustdoc-stripper-ignore-next
    /// Creates a new builder-pattern struct instance to construct [`Cursor`] objects.
    ///
    /// This method returns an instance of [`CursorBuilder`](crate::builders::CursorBuilder) which can be used to create [`Cursor`] objects.
    pub fn builder() -> CursorBuilder {
        CursorBuilder::new()
    }

    /// Returns the fallback for this @self.
    ///
    /// The fallback will be used if this cursor is not available on a given
    /// [`Display`][crate::Display]. For named cursors, this can happen when using nonstandard
    /// names or when using an incomplete cursor theme. For textured cursors,
    /// this can happen when the texture is too large or when the [`Display`][crate::Display]
    /// it is used on does not support textured cursors.
    ///
    /// # Returns
    ///
    /// the fallback of the cursor or [`None`]
    ///   to use the default cursor as fallback
    #[doc(alias = "gdk_cursor_get_fallback")]
    #[doc(alias = "get_fallback")]
    #[must_use]
    pub fn fallback(&self) -> Option<Cursor> {
        unsafe { from_glib_none(ffi::gdk_cursor_get_fallback(self.to_glib_none().0)) }
    }

    /// Returns the horizontal offset of the hotspot.
    ///
    /// The hotspot indicates the pixel that will be directly above the cursor.
    ///
    /// Note that named cursors may have a nonzero hotspot, but this function
    /// will only return the hotspot position for cursors created with
    /// [`from_texture()`][Self::from_texture()].
    ///
    /// # Returns
    ///
    /// the horizontal offset of the hotspot or 0 for named cursors
    #[doc(alias = "gdk_cursor_get_hotspot_x")]
    #[doc(alias = "get_hotspot_x")]
    #[doc(alias = "hotspot-x")]
    pub fn hotspot_x(&self) -> i32 {
        unsafe { ffi::gdk_cursor_get_hotspot_x(self.to_glib_none().0) }
    }

    /// Returns the vertical offset of the hotspot.
    ///
    /// The hotspot indicates the pixel that will be directly above the cursor.
    ///
    /// Note that named cursors may have a nonzero hotspot, but this function
    /// will only return the hotspot position for cursors created with
    /// [`from_texture()`][Self::from_texture()].
    ///
    /// # Returns
    ///
    /// the vertical offset of the hotspot or 0 for named cursors
    #[doc(alias = "gdk_cursor_get_hotspot_y")]
    #[doc(alias = "get_hotspot_y")]
    #[doc(alias = "hotspot-y")]
    pub fn hotspot_y(&self) -> i32 {
        unsafe { ffi::gdk_cursor_get_hotspot_y(self.to_glib_none().0) }
    }

    /// Returns the name of the cursor.
    ///
    /// If the cursor is not a named cursor, [`None`] will be returned.
    ///
    /// # Returns
    ///
    /// the name of the cursor or [`None`]
    ///   if it is not a named cursor
    #[doc(alias = "gdk_cursor_get_name")]
    #[doc(alias = "get_name")]
    pub fn name(&self) -> Option<glib::GString> {
        unsafe { from_glib_none(ffi::gdk_cursor_get_name(self.to_glib_none().0)) }
    }

    /// Returns the texture for the cursor.
    ///
    /// If the cursor is a named cursor, [`None`] will be returned.
    ///
    /// # Returns
    ///
    /// the texture for cursor or [`None`]
    ///   if it is a named cursor
    #[doc(alias = "gdk_cursor_get_texture")]
    #[doc(alias = "get_texture")]
    pub fn texture(&self) -> Option<Texture> {
        unsafe { from_glib_none(ffi::gdk_cursor_get_texture(self.to_glib_none().0)) }
    }
}

// rustdoc-stripper-ignore-next
/// A [builder-pattern] type to construct [`Cursor`] objects.
///
/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
#[must_use = "The builder must be built to be used"]
pub struct CursorBuilder {
    builder: glib::object::ObjectBuilder<'static, Cursor>,
}

impl CursorBuilder {
    fn new() -> Self {
        Self {
            builder: glib::object::Object::builder(),
        }
    }

    /// Cursor to fall back to if this cursor cannot be displayed.
    pub fn fallback(self, fallback: &Cursor) -> Self {
        Self {
            builder: self.builder.property("fallback", fallback.clone()),
        }
    }

    /// X position of the cursor hotspot in the cursor image.
    pub fn hotspot_x(self, hotspot_x: i32) -> Self {
        Self {
            builder: self.builder.property("hotspot-x", hotspot_x),
        }
    }

    /// Y position of the cursor hotspot in the cursor image.
    pub fn hotspot_y(self, hotspot_y: i32) -> Self {
        Self {
            builder: self.builder.property("hotspot-y", hotspot_y),
        }
    }

    /// Name of this this cursor.
    ///
    /// The name will be [`None`] if the cursor was created from a texture.
    pub fn name(self, name: impl Into<glib::GString>) -> Self {
        Self {
            builder: self.builder.property("name", name.into()),
        }
    }

    /// The texture displayed by this cursor.
    ///
    /// The texture will be [`None`] if the cursor was created from a name.
    pub fn texture(self, texture: &impl IsA<Texture>) -> Self {
        Self {
            builder: self.builder.property("texture", texture.clone().upcast()),
        }
    }

    // rustdoc-stripper-ignore-next
    /// Build the [`Cursor`].
    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
    pub fn build(self) -> Cursor {
        self.builder.build()
    }
}