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}