bevy_window/cursor/
custom_cursor.rs

1use crate::cursor::CursorIcon;
2use alloc::string::String;
3use bevy_asset::Handle;
4use bevy_image::{Image, TextureAtlas};
5use bevy_math::URect;
6
7#[cfg(feature = "bevy_reflect")]
8use bevy_reflect::{std_traits::ReflectDefault, Reflect};
9
10/// A custom cursor created from an image.
11#[derive(Debug, Clone, Default, PartialEq, Eq, Hash)]
12#[cfg_attr(
13    feature = "bevy_reflect",
14    derive(Reflect),
15    reflect(Debug, Default, Hash, PartialEq, Clone)
16)]
17pub struct CustomCursorImage {
18    /// Handle to the image to use as the cursor. The image must be in 8 bit int
19    /// or 32 bit float rgba. PNG images work well for this.
20    pub handle: Handle<Image>,
21    /// An optional texture atlas used to render the image.
22    pub texture_atlas: Option<TextureAtlas>,
23    /// Whether the image should be flipped along its x-axis.
24    ///
25    /// If true, the cursor's `hotspot` automatically flips along with the
26    /// image.
27    pub flip_x: bool,
28    /// Whether the image should be flipped along its y-axis.
29    ///
30    /// If true, the cursor's `hotspot` automatically flips along with the
31    /// image.
32    pub flip_y: bool,
33    /// An optional rectangle representing the region of the image to render,
34    /// instead of rendering the full image. This is an easy one-off alternative
35    /// to using a [`TextureAtlas`].
36    ///
37    /// When used with a [`TextureAtlas`], the rect is offset by the atlas's
38    /// minimal (top-left) corner position.
39    pub rect: Option<URect>,
40    /// X and Y coordinates of the hotspot in pixels. The hotspot must be within
41    /// the image bounds.
42    ///
43    /// If you are flipping the image using `flip_x` or `flip_y`, you don't need
44    /// to adjust this field to account for the flip because it is adjusted
45    /// automatically.
46    pub hotspot: (u16, u16),
47}
48
49/// A custom cursor created from a URL. Note that this currently only works on the web.
50#[derive(Debug, Clone, Default, PartialEq, Eq, Hash)]
51#[cfg_attr(
52    feature = "bevy_reflect",
53    derive(Reflect),
54    reflect(Debug, Default, Hash, PartialEq, Clone)
55)]
56pub struct CustomCursorUrl {
57    /// Web URL to an image to use as the cursor. PNGs are preferred. Cursor
58    /// creation can fail if the image is invalid or not reachable.
59    pub url: String,
60    /// X and Y coordinates of the hotspot in pixels. The hotspot must be within
61    /// the image bounds.
62    pub hotspot: (u16, u16),
63}
64
65/// Custom cursor image data.
66#[derive(Debug, Clone, PartialEq, Eq, Hash)]
67#[cfg_attr(
68    feature = "bevy_reflect",
69    derive(Reflect),
70    reflect(Clone, PartialEq, Hash)
71)]
72pub enum CustomCursor {
73    /// Use an image as the cursor.
74    Image(CustomCursorImage),
75    /// Use a URL to an image as the cursor. Note that this currently only works on the web.
76    Url(CustomCursorUrl),
77}
78
79impl From<CustomCursor> for CursorIcon {
80    fn from(cursor: CustomCursor) -> Self {
81        CursorIcon::Custom(cursor)
82    }
83}