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! {
    /// 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"          | No cursor |
    /// | ![](default_cursor.png)       | "default"       | The default cursor |
    /// | ![](help_cursor.png)          | "help"          | Help is available |
    /// | ![](pointer_cursor.png)       | "pointer"       | Indicates a link or interactive element |
    /// | ![](context_menu_cursor.png)  |"context-menu"   | A context menu is available |
    /// | ![](progress_cursor.png)      | "progress"      | Progress indicator |
    /// | ![](wait_cursor.png)          | "wait"          | Busy cursor |
    /// | ![](cell_cursor.png)          | "cell"          | Cell(s) may be selected |
    /// | ![](crosshair_cursor.png)     | "crosshair"     | Simple crosshair |
    /// | ![](text_cursor.png)          | "text"          | Text may be selected |
    /// | ![](vertical_text_cursor.png) | "vertical-text" | Vertical text may be selected |
    /// | ![](alias_cursor.png)         | "alias"         | DND: Something will be linked |
    /// | ![](copy_cursor.png)          | "copy"          | DND: Something will be copied |
    /// | ![](move_cursor.png)          | "move"          | DND: Something will be moved |
    /// | ![](dnd_ask_cursor.png)       | "dnd-ask"       | DND: User can choose action to be carried out |
    /// | ![](no_drop_cursor.png)       | "no-drop"       | DND: Can't drop here |
    /// | ![](not_allowed_cursor.png)   | "not-allowed"   | DND: Action will not be carried out |
    /// | ![](grab_cursor.png)          | "grab"          | DND: Something can be grabbed |
    /// | ![](grabbing_cursor.png)      | "grabbing"      | DND: Something is being grabbed |
    /// | ![](n_resize_cursor.png)      | "n-resize"      | Resizing: Move north border |
    /// | ![](e_resize_cursor.png)      | "e-resize"      | Resizing: Move east border |
    /// | ![](s_resize_cursor.png)      | "s-resize"      | Resizing: Move south border |
    /// | ![](w_resize_cursor.png)      | "w-resize"      | Resizing: Move west border |
    /// | ![](ne_resize_cursor.png)     | "ne-resize"     | Resizing: Move north-east corner |
    /// | ![](nw_resize_cursor.png)     | "nw-resize"     | Resizing: Move north-west corner |
    /// | ![](sw_resize_cursor.png)     | "sw-resize"     | Resizing: Move south-west corner |
    /// | ![](se_resize_cursor.png)     | "se-resize"     | Resizing: Move south-east corner |
    /// | ![](col_resize_cursor.png)    | "col-resize"    | Resizing: Move an item or border horizontally |
    /// | ![](row_resize_cursor.png)    | "row-resize"    | Resizing: Move an item or border vertically |
    /// | ![](ew_resize_cursor.png)     | "ew-resize"     | Moving: Something can be moved horizontally |
    /// | ![](ns_resize_cursor.png)     | "ns-resize"     | Moving: Something can be moved vertically |
    /// | ![](nesw_resize_cursor.png)   | "nesw-resize"   | Moving: Something can be moved diagonally, north-east to south-west |
    /// | ![](nwse_resize_cursor.png)   | "nwse-resize"   | Moving: something can be moved diagonally, north-west to south-east |
    /// | ![](all_resize_cursor.png)    | "all-resize"    | Moving: Something can be moved in any direction |
    /// | ![](all_scroll_cursor.png)    | "all-scroll"    | Can scroll in any direction |
    /// | ![](zoom_in_cursor.png)       | "zoom-in"       | Zoom in |
    /// | ![](zoom_out_cursor.png)      | "zoom-out"      | 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 {
        assert_initialized_main_thread!();
        self.builder.build()
    }
}