Add ability to create Icons from embedded resources on Windows (#1410)

* Add IconExtWindows trait

* Move changelog entries to unreleased category

Co-authored-by: Osspial <[email protected]>

Author: davidhewitt

CHANGELOG.md

@@ -12,6 +12,8 @@
 - On Wayland, Hide CSD for fullscreen windows.
 - On Windows, ignore spurious mouse move messages.
 - **Breaking:** Move `ModifiersChanged` variant from `DeviceEvent` to `WindowEvent`.
+- On Windows, add `IconExtWindows` trait which exposes creating an `Icon` from an external file or embedded resource
+- Add `BadIcon::OsError` variant for when OS icon functionality fails
 - On Windows, fix crash at startup on systems that do not properly support Windows' Dark Mode
 
 # 0.21.0 (2020-02-04)

src/icon.rs

@@ -1,4 +1,5 @@
-use std::{error::Error, fmt, mem};
+use crate::platform_impl::PlatformIcon;
+use std::{error::Error, fmt, io, mem};
 
 #[repr(C)]
 #[derive(Debug)]
@@ -11,7 +12,7 @@ pub(crate) struct Pixel {
 
 pub(crate) const PIXEL_SIZE: usize = mem::size_of::<Pixel>();
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Debug)]
 /// An error produced when using `Icon::from_rgba` with invalid arguments.
 pub enum BadIcon {
     /// Produced when the length of the `rgba` argument isn't divisible by 4, thus `rgba` can't be
@@ -25,6 +26,8 @@ pub enum BadIcon {
         width_x_height: usize,
         pixel_count: usize,
     },
+    /// Produced when underlying OS functionality failed to create the icon
+    OsError(io::Error),
 }
 
 impl fmt::Display for BadIcon {
@@ -43,6 +46,7 @@ impl fmt::Display for BadIcon {
                 "The specified dimensions ({:?}x{:?}) don't match the number of pixels supplied by the `rgba` argument ({:?}). For those dimensions, the expected pixel count is {:?}.",
                 width, height, pixel_count, width_x_height,
             ),
+            BadIcon::OsError(e) => write!(f, "OS error when instantiating the icon: {:?}", e),
         }
     }
 }
@@ -54,38 +58,78 @@ impl Error for BadIcon {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
-/// An icon used for the window titlebar, taskbar, etc.
-pub struct Icon {
+pub(crate) struct RgbaIcon {
     pub(crate) rgba: Vec<u8>,
     pub(crate) width: u32,
     pub(crate) height: u32,
 }
 
+/// For platforms which don't have window icons (e.g. web)
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct NoIcon;
+
+#[allow(dead_code)] // These are not used on every platform
+mod constructors {
+    use super::*;
+
+    impl RgbaIcon {
+        /// Creates an `Icon` from 32bpp RGBA data.
+        ///
+        /// The length of `rgba` must be divisible by 4, and `width * height` must equal
+        /// `rgba.len() / 4`. Otherwise, this will return a `BadIcon` error.
+        pub fn from_rgba(rgba: Vec<u8>, width: u32, height: u32) -> Result<Self, BadIcon> {
+            if rgba.len() % PIXEL_SIZE != 0 {
+                return Err(BadIcon::ByteCountNotDivisibleBy4 {
+                    byte_count: rgba.len(),
+                });
+            }
+            let pixel_count = rgba.len() / PIXEL_SIZE;
+            if pixel_count != (width * height) as usize {
+                Err(BadIcon::DimensionsVsPixelCount {
+                    width,
+                    height,
+                    width_x_height: (width * height) as usize,
+                    pixel_count,
+                })
+            } else {
+                Ok(RgbaIcon {
+                    rgba,
+                    width,
+                    height,
+                })
+            }
+        }
+    }
+
+    impl NoIcon {
+        pub fn from_rgba(rgba: Vec<u8>, width: u32, height: u32) -> Result<Self, BadIcon> {
+            // Create the rgba icon anyway to validate the input
+            let _ = RgbaIcon::from_rgba(rgba, width, height)?;
+            Ok(NoIcon)
+        }
+    }
+}
+
+/// An icon used for the window titlebar, taskbar, etc.
+#[derive(Clone)]
+pub struct Icon {
+    pub(crate) inner: PlatformIcon,
+}
+
+impl fmt::Debug for Icon {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
+        fmt::Debug::fmt(&self.inner, formatter)
+    }
+}
+
 impl Icon {
     /// Creates an `Icon` from 32bpp RGBA data.
     ///
     /// The length of `rgba` must be divisible by 4, and `width * height` must equal
     /// `rgba.len() / 4`. Otherwise, this will return a `BadIcon` error.
     pub fn from_rgba(rgba: Vec<u8>, width: u32, height: u32) -> Result<Self, BadIcon> {
-        if rgba.len() % PIXEL_SIZE != 0 {
-            return Err(BadIcon::ByteCountNotDivisibleBy4 {
-                byte_count: rgba.len(),
-            });
-        }
-        let pixel_count = rgba.len() / PIXEL_SIZE;
-        if pixel_count != (width * height) as usize {
-            Err(BadIcon::DimensionsVsPixelCount {
-                width,
-                height,
-                width_x_height: (width * height) as usize,
-                pixel_count,
-            })
-        } else {
-            Ok(Icon {
-                rgba,
-                width,
-                height,
-            })
-        }
+        Ok(Icon {
+            inner: PlatformIcon::from_rgba(rgba, width, height)?,
+        })
     }
 }

src/platform/windows.rs

@@ -1,16 +1,19 @@
 #![cfg(target_os = "windows")]
 
 use std::os::raw::c_void;
+use std::path::Path;
 
 use libc;
+use winapi::shared::minwindef::WORD;
 use winapi::shared::windef::HWND;
 
 use crate::{
+    dpi::PhysicalSize,
     event::DeviceId,
     event_loop::EventLoop,
     monitor::MonitorHandle,
-    platform_impl::EventLoop as WindowsEventLoop,
-    window::{Icon, Window, WindowBuilder},
+    platform_impl::{EventLoop as WindowsEventLoop, WinIcon},
+    window::{BadIcon, Icon, Window, WindowBuilder},
 };
 
 /// Additional methods on `EventLoop` that are specific to Windows.
@@ -171,3 +174,40 @@ impl DeviceIdExtWindows for DeviceId {
         self.0.persistent_identifier()
     }
 }
+
+/// Additional methods on `Icon` that are specific to Windows.
+pub trait IconExtWindows: Sized {
+    /// Create an icon from a file path.
+    ///
+    /// Specify `size` to load a specific icon size from the file, or `None` to load the default
+    /// icon size from the file.
+    ///
+    /// In cases where the specified size does not exist in the file, Windows may perform scaling
+    /// to get an icon of the desired size.
+    fn from_path<P: AsRef<Path>>(path: P, size: Option<PhysicalSize<u32>>)
+        -> Result<Self, BadIcon>;
+
+    /// Create an icon from a resource embedded in this executable or library.
+    ///
+    /// Specify `size` to load a specific icon size from the file, or `None` to load the default
+    /// icon size from the file.
+    ///
+    /// In cases where the specified size does not exist in the file, Windows may perform scaling
+    /// to get an icon of the desired size.
+    fn from_resource(ordinal: WORD, size: Option<PhysicalSize<u32>>) -> Result<Self, BadIcon>;
+}
+
+impl IconExtWindows for Icon {
+    fn from_path<P: AsRef<Path>>(
+        path: P,
+        size: Option<PhysicalSize<u32>>,
+    ) -> Result<Self, BadIcon> {
+        let win_icon = WinIcon::from_path(path, size)?;
+        Ok(Icon { inner: win_icon })
+    }
+
+    fn from_resource(ordinal: WORD, size: Option<PhysicalSize<u32>>) -> Result<Self, BadIcon> {
+        let win_icon = WinIcon::from_resource(ordinal, size)?;
+        Ok(Icon { inner: win_icon })
+    }
+}

src/platform_impl/android/mod.rs

@@ -22,6 +22,8 @@ use crate::{
 use raw_window_handle::{android::AndroidHandle, RawWindowHandle};
 use CreationError::OsError;
 
+pub(crate) use crate::icon::NoIcon as PlatformIcon;
+
 pub type OsError = std::io::Error;
 
 pub struct EventLoop {

src/platform_impl/ios/mod.rs

@@ -83,6 +83,8 @@ pub use self::{
     window::{PlatformSpecificWindowBuilderAttributes, Window, WindowId},
 };
 
+pub(crate) use crate::icon::NoIcon as PlatformIcon;
+
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct DeviceId {
     uiscreen: ffi::id,

src/platform_impl/linux/mod.rs

@@ -18,6 +18,8 @@ use crate::{
     window::{CursorIcon, Fullscreen, WindowAttributes},
 };
 
+pub(crate) use crate::icon::RgbaIcon as PlatformIcon;
+
 pub mod wayland;
 pub mod x11;
 

src/platform_impl/linux/x11/util/icon.rs

@@ -1,5 +1,5 @@
 use super::*;
-use crate::window::{Icon, Pixel, PIXEL_SIZE};
+use crate::icon::{Icon, Pixel, PIXEL_SIZE};
 
 impl Pixel {
     pub fn to_packed_argb(&self) -> Cardinal {
@@ -18,13 +18,14 @@ impl Pixel {
 
 impl Icon {
     pub(crate) fn to_cardinals(&self) -> Vec<Cardinal> {
-        assert_eq!(self.rgba.len() % PIXEL_SIZE, 0);
-        let pixel_count = self.rgba.len() / PIXEL_SIZE;
-        assert_eq!(pixel_count, (self.width * self.height) as usize);
+        let rgba_icon = &self.inner;
+        assert_eq!(rgba_icon.rgba.len() % PIXEL_SIZE, 0);
+        let pixel_count = rgba_icon.rgba.len() / PIXEL_SIZE;
+        assert_eq!(pixel_count, (rgba_icon.width * rgba_icon.height) as usize);
         let mut data = Vec::with_capacity(pixel_count);
-        data.push(self.width as Cardinal);
-        data.push(self.height as Cardinal);
-        let pixels = self.rgba.as_ptr() as *const Pixel;
+        data.push(rgba_icon.width as Cardinal);
+        data.push(rgba_icon.height as Cardinal);
+        let pixels = rgba_icon.rgba.as_ptr() as *const Pixel;
         for pixel_index in 0..pixel_count {
             let pixel = unsafe { &*pixels.offset(pixel_index as isize) };
             data.push(pixel.to_packed_argb());

src/platform_impl/macos/mod.rs

@@ -25,6 +25,8 @@ use crate::{
     error::OsError as RootOsError, event::DeviceId as RootDeviceId, window::WindowAttributes,
 };
 
+pub(crate) use crate::icon::NoIcon as PlatformIcon;
+
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct DeviceId;
 

src/platform_impl/web/mod.rs

@@ -44,3 +44,5 @@ pub use self::window::{
     Id as WindowId, PlatformSpecificBuilderAttributes as PlatformSpecificWindowBuilderAttributes,
     Window,
 };
+
+pub(crate) use crate::icon::NoIcon as PlatformIcon;