add action set icon while running (#1590)

* set windows icon live action

* change get icon to insto raw

* remove mobile docs

* format

* fix format

* add file methods to Icon

* Rename action to `ChangeIcon` and tidy up `Icon` modules

* Fix documentation of `icon::Error`

* Remove unnecessary `\` in `icon` documentation

* Remove `etc.` from `Icon` documentation

---------

Co-authored-by: Héctor Ramón Jiménez <hector0193@gmail.com>

native/src/window.rs

@@ -5,8 +5,11 @@ mod mode;
 mod redraw_request;
 mod user_attention;
 
+pub mod icon;
+
 pub use action::Action;
 pub use event::Event;
+pub use icon::Icon;
 pub use mode::Mode;
 pub use redraw_request::RedrawRequest;
 pub use user_attention::UserAttention;

native/src/window/action.rs

@@ -1,4 +1,4 @@
-use crate::window::{Mode, UserAttention};
+use crate::window::{Icon, Mode, UserAttention};
 
 use iced_futures::MaybeSend;
 use std::fmt;
@@ -78,6 +78,21 @@ pub enum Action<T> {
     ChangeAlwaysOnTop(bool),
     /// Fetch an identifier unique to the window.
     FetchId(Box<dyn FnOnce(u64) -> T + 'static>),
+    /// Changes the window [`Icon`].
+    ///
+    /// On Windows and X11, this is typically the small icon in the top-left
+    /// corner of the titlebar.
+    ///
+    /// ## Platform-specific
+    ///
+    /// - **Web / Wayland / macOS:** Unsupported.
+    ///
+    /// - **Windows:** Sets `ICON_SMALL`. The base size for a window icon is 16x16, but it's
+    ///   recommended to account for screen scaling and pick a multiple of that, i.e. 32x32.
+    ///
+    /// - **X11:** Has no universal guidelines for icon sizes, so you're at the whims of the WM. That
+    ///   said, it's usually in the same ballpark as on Windows.
+    ChangeIcon(Icon),
 }
 
 impl<T> Action<T> {
@@ -108,6 +123,7 @@ impl<T> Action<T> {
                 Action::ChangeAlwaysOnTop(on_top)
             }
             Self::FetchId(o) => Action::FetchId(Box::new(move |s| f(o(s)))),
+            Self::ChangeIcon(icon) => Action::ChangeIcon(icon),
         }
     }
 }
@@ -142,6 +158,9 @@ impl<T> fmt::Debug for Action<T> {
                 write!(f, "Action::AlwaysOnTop({on_top})")
             }
             Self::FetchId(_) => write!(f, "Action::FetchId"),
+            Self::ChangeIcon(_icon) => {
+                write!(f, "Action::ChangeIcon(icon)")
+            }
         }
     }
 }

native/src/window/icon.rs

@@ -0,0 +1,80 @@
+//! Change the icon of a window.
+use crate::Size;
+
+use std::mem;
+
+/// Builds an  [`Icon`] from its RGBA pixels in the sRGB color space.
+pub fn from_rgba(
+    rgba: Vec<u8>,
+    width: u32,
+    height: u32,
+) -> Result<Icon, Error> {
+    const PIXEL_SIZE: usize = mem::size_of::<u8>() * 4;
+
+    if rgba.len() % PIXEL_SIZE != 0 {
+        return Err(Error::ByteCountNotDivisibleBy4 {
+            byte_count: rgba.len(),
+        });
+    }
+
+    let pixel_count = rgba.len() / PIXEL_SIZE;
+
+    if pixel_count != (width * height) as usize {
+        return Err(Error::DimensionsVsPixelCount {
+            width,
+            height,
+            width_x_height: (width * height) as usize,
+            pixel_count,
+        });
+    }
+
+    Ok(Icon {
+        rgba,
+        size: Size::new(width, height),
+    })
+}
+
+/// An window icon normally used for the titlebar or taskbar.
+#[derive(Debug, Clone)]
+pub struct Icon {
+    rgba: Vec<u8>,
+    size: Size<u32>,
+}
+
+impl Icon {
+    /// Returns the raw data of the [`Icon`].
+    pub fn into_raw(self) -> (Vec<u8>, Size<u32>) {
+        (self.rgba, self.size)
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+/// An error produced when using [`Icon::from_rgba`] with invalid arguments.
+pub enum Error {
+    /// Produced when the length of the `rgba` argument isn't divisible by 4, thus `rgba` can't be
+    /// safely interpreted as 32bpp RGBA pixels.
+    #[error(
+        "The provided RGBA data (with length {byte_count}) isn't divisible \
+        by 4. Therefore, it cannot be safely interpreted as 32bpp RGBA pixels"
+    )]
+    ByteCountNotDivisibleBy4 {
+        /// The length of the provided RGBA data.
+        byte_count: usize,
+    },
+    /// Produced when the number of pixels (`rgba.len() / 4`) isn't equal to `width * height`.
+    /// At least one of your arguments is incorrect.
+    #[error(
+        "The number of RGBA pixels ({pixel_count}) does not match the \
+        provided dimensions ({width}x{height})."
+    )]
+    DimensionsVsPixelCount {
+        /// The provided width.
+        width: u32,
+        /// The provided height.
+        height: u32,
+        /// The product of `width` and `height`.
+        width_x_height: usize,
+        /// The amount of pixels of the provided RGBA data.
+        pixel_count: usize,
+    },
+}