Finish 0.4 update

CHANGELOG.md

@@ -2,10 +2,16 @@
 
 ## 0.4.0 (?)
 
-* **Breaking:** Change type for pointers, which may be null, to `Option<NonNull<_>>`.
 * **Breaking:** Remove `_do_not_use` tags to use `#[non_exhaustive]` macro
 * Added `TrustedWindowHandle::from_has_raw_window_handle`.
-* **Breaking:** handle variants are no longer cfg-guarded by platform.
+* **Breaking:** `RawWindowHandle` variants are no longer cfg-guarded by platform. 
+* **Breaking:** Rename `IOS` to `UiKit`.
+* **Breaking:** Rename `MacOS` to `AppKit`.
+* **Breaking:** Rename `Windows` to `Win32`.
+* **Breaking:** Rename `Redox` to `Orbital`.
+* **Breaking:** Rename `Android` to `AndroidNdk`.
+* **Breaking:** Inner window handle structs are now exported at crate root.
+* Added Windows `WinRt` handle.
 
 ## 0.3.3 (2019-12-1)
 

src/android.rs

@@ -1,25 +1,25 @@
 use core::ffi::c_void;
-use core::ptr::NonNull;
+use core::ptr;
 
-/// Raw window handle for Android.
+/// Raw window handle for Android NDK.
 ///
 /// ## Construction
 /// ```
-/// # use raw_window_handle::android::AndroidHandle;
-/// let mut handle = AndroidHandle::empty();
-///  /* set fields */
+/// # use raw_window_handle::AndroidNdkHandle;
+/// let mut handle = AndroidNdkHandle::empty();
+/// /* set fields */
 /// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct AndroidHandle {
- /// A pointer to an ANativeWindow.
- pub a_native_window: Option<NonNull<c_void>>,
+pub struct AndroidNdkHandle {
+ /// A pointer to an `ANativeWindow`.
+ pub a_native_window: *mut c_void,
 }
 
-impl AndroidHandle {
- pub fn empty() -> AndroidHandle {
- AndroidHandle {
- a_native_window: None,
+impl AndroidNdkHandle {
+ pub fn empty() -> Self {
+ Self {
+ a_native_window: ptr::null_mut(),
  }
  }
 }

src/appkit.rs

@@ -0,0 +1,29 @@
+use core::ffi::c_void;
+use core::ptr;
+
+/// Raw window handle for AppKit.
+///
+/// ## Construction
+/// ```
+/// # use raw_window_handle::AppKitHandle;
+/// let mut handle = AppKitHandle::empty();
+/// /* set fields */
+/// ```
+#[non_exhaustive]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct AppKitHandle {
+ /// A pointer to an `NSWindow` object.
+ pub ns_window: *mut c_void,
+ /// A pointer to an `NSView` object.
+ pub ns_view: *mut c_void,
+ // TODO: WHAT ABOUT ns_window_controller and ns_view_controller?
+}
+
+impl AppKitHandle {
+ pub fn empty() -> Self {
+ Self {
+ ns_window: ptr::null_mut(),
+ ns_view: ptr::null_mut(),
+ }
+ }
+}

src/lib.rs

@@ -7,20 +7,32 @@
 //! provides a common interface that window creation libraries (e.g. Winit, SDL) can use to easily
 //! talk with graphics libraries (e.g. gfx-hal).
 //!
+//! ## Safety guarantees
+//!
+//! Please see the docs of [`HasRawWindowHandle`].
+//!
 //! ## Platform handle initialization
 //!
 //! Each platform handle struct is purposefully non-exhaustive, so that additional fields may be
 //! added without breaking backwards compatibility. Each struct provides an `empty` method that may
 //! be used along with the struct update syntax to construct it. See each specific struct for
 //! examples.
 
-pub mod android;
-pub mod ios;
-pub mod macos;
-pub mod redox;
-pub mod unix;
-pub mod web;
-pub mod windows;
+mod android;
+mod appkit;
+mod redox;
+mod uikit;
+mod unix;
+mod web;
+mod windows;
+
+pub use android::AndroidNdkHandle;
+pub use appkit::AppKitHandle;
+pub use redox::OrbitalHandle;
+pub use uikit::UiKitHandle;
+pub use unix::{WaylandHandle, XcbHandle, XlibHandle};
+pub use web::WebHandle;
+pub use windows::{Win32Handle, WinRtHandle};
 
 /// Window that wraps around a raw window handle.
 ///
@@ -41,28 +53,82 @@ pub unsafe trait HasRawWindowHandle {
 }
 
 /// An enum to simply combine the different possible raw window handle variants.
+///
+/// # Variant Availability
+///
+/// Note that all variants are present on all targets (none are disabled behind
+/// `#[cfg]`s), but see the "Availability Hints" section on each variant for
+/// some hints on where this variant might be expected.
+///
+/// Note that these "Availability Hints" are not normative. That is to say, a
+/// [`HasRawWindowHandle`] implementor is completely allowed to return something
+/// unexpected. (For example, it's legal for someone to return a
+/// [`RawWindowHandle::Xlib`] on macOS, it would just be weird, and probably
+/// requires something like XQuartz be used).
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum RawWindowHandle {
- IOS(ios::IOSHandle),
-
- MacOS(macos::MacOSHandle),
-
- Redox(redox::RedoxHandle),
-
- Xlib(unix::XlibHandle),
-
- Xcb(unix::XcbHandle),
-
- Wayland(unix::WaylandHandle),
-
- Windows(windows::WindowsHandle),
-
- WinRT(windows::WinRTHandle),
-
- Web(web::WebHandle),
-
- Android(android::AndroidHandle),
+ /// A raw window handle for UIKit (Apple's non-macOS windowing library).
+ ///
+ /// ## Availability Hints
+ /// This variant is likely to be used on iOS, tvOS, (in theory) watchOS, and
+ /// Mac Catalyst (`$arch-apple-ios-macabi` targets, which can notably use
+ /// UIKit *or* AppKit), as these are the targets that (currently) support
+ /// UIKit.
+ UiKit(UiKitHandle),
+ /// A raw window handle for AppKit.
+ ///
+ /// ## Availability Hints
+ /// This variant is likely to be used on macOS, although Mac Catalyst
+ /// (`$arch-apple-ios-macabi` targets, which can notably use UIKit *or*
+ /// AppKit) can also use it despite being `target_os = "ios"`.
+ AppKit(AppKitHandle),
+ /// A raw window handle for the Redox operating system.
+ ///
+ /// ## Availability Hints
+ /// This variant is used by the Orbital Windowing System in the Redox
+ /// operating system.
+ Orbital(OrbitalHandle),
+ /// A raw window handle for Xlib.
+ ///
+ /// ## Availability Hints
+ /// This variant is likely to show up anywhere someone manages to get X11
+ /// working that Xlib can be built for, which is to say, most (but not all)
+ /// Unix systems.
+ Xlib(XlibHandle),
+ /// A raw window handle for Xcb.
+ ///
+ /// ## Availability Hints
+ /// This variant is likely to show up anywhere someone manages to get X11
+ /// working that XCB can be built for, which is to say, most (but not all)
+ /// Unix systems.
+ Xcb(XcbHandle),
+ /// A raw window handle for Wayland.
+ ///
+ /// ## Availability Hints
+ /// This variant should be expected anywhere Wayland works, which is
+ /// currently some subset of unix systems.
+ Wayland(WaylandHandle),
+ /// A raw window handle for Win32.
+ ///
+ /// ## Availability Hints
+ /// This variant is used on Windows systems.
+ Win32(Win32Handle),
+ /// A raw window handle for WinRT.
+ ///
+ /// ## Availability Hints
+ /// This variant is used on Windows systems.
+ WinRt(WinRtHandle),
+ /// A raw window handle for the Web.
+ ///
+ /// ## Availability Hints
+ /// This variant is used on Wasm or asm.js targets when targeting the Web/HTML5.
+ Web(WebHandle),
+ /// A raw window handle for Android NDK.
+ ///
+ /// ## Availability Hints
+ /// This variant is used on Android targets.
+ AndroidNdk(AndroidNdkHandle),
 }
 
 /// This wraps a [`RawWindowHandle`] to give it a [`HasRawWindowHandle`] impl.
@@ -77,6 +143,7 @@ pub enum RawWindowHandle {
 pub struct TrustedWindowHandle {
  raw: RawWindowHandle,
 }
+
 impl TrustedWindowHandle {
  /// Assert that the [`RawWindowHandle`] value can be trusted.
  ///
@@ -97,6 +164,7 @@ impl TrustedWindowHandle {
  }
  }
 }
+
 unsafe impl HasRawWindowHandle for TrustedWindowHandle {
  fn raw_window_handle(&self) -> RawWindowHandle {
  self.raw

src/redox.rs

@@ -1,24 +1,24 @@
 use core::ffi::c_void;
 use core::ptr;
 
-/// Raw window handle for Redox OS.
+/// Raw window handle for the Redox operating system.
 ///
 /// ## Construction
 /// ```
-/// # use raw_window_handle::redox::RedoxHandle;
-/// let mut handle = RedoxHandle::empty();
-///  /* set fields */
+/// # use raw_window_handle::OrbitalHandle;
+/// let mut handle = OrbitalHandle::empty();
+/// /* set fields */
 /// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct RedoxHandle {
+pub struct OrbitalHandle {
  /// A pointer to an orbclient window.
  pub window: *mut c_void,
 }
 
-impl RedoxHandle {
- pub fn empty() -> RedoxHandle {
- RedoxHandle {
+impl OrbitalHandle {
+ pub fn empty() -> Self {
+ Self {
  window: ptr::null_mut(),
  }
  }

src/uikit.rs

@@ -0,0 +1,31 @@
+use core::ffi::c_void;
+use core::ptr;
+
+/// Raw window handle for UIKit.
+///
+/// ## Construction
+/// ```
+/// # use raw_window_handle::UiKitHandle;
+/// let mut handle = UiKitHandle::empty();
+/// /* set fields */
+/// ```
+#[non_exhaustive]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct UiKitHandle {
+ /// A pointer to an `UIWindow` object.
+ pub ui_window: *mut c_void,
+ /// A pointer to an `UIView` object.
+ pub ui_view: *mut c_void,
+ /// A pointer to an `UIViewController` object.
+ pub ui_view_controller: *mut c_void,
+}
+
+impl UiKitHandle {
+ pub fn empty() -> Self {
+ Self {
+ ui_window: ptr::null_mut(),
+ ui_view: ptr::null_mut(),
+ ui_view_controller: ptr::null_mut(),
+ }
+ }
+}