Finish 0.4 update

CHANGELOG.md

@@ -2,10 +2,15 @@
 
 ## 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.
 
 ## 0.3.3 (2019-12-1)
 
@@ -43,4 +48,4 @@
 
 ## 0.1.0 (2019-08-13)
 
-* Initial release.
+* Initial release.

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() -> AndroidNDKHandle {
+        AndroidNDKHandle {
+            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() -> AppKitHandle {
+        AppKitHandle {
+            ns_window: ptr::null_mut(),
+            ns_view: ptr::null_mut(),
+        }
+    }
+}

src/lib.rs

@@ -14,13 +14,21 @@
 //! 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 +49,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),
-
+    /// 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(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(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(redox::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(unix::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(unix::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(unix::WaylandHandle),
-
-    Windows(windows::WindowsHandle),
-
+    /// A raw window handle for Win32.
+    ///
+    /// ## Availability Hints
+    /// This variant is used on Windows systems.
+    Win32(windows::Win32Handle),
+    /// A raw window handle for WinRT.
+    ///
+    /// ## Availability Hints
+    /// This variant is used on Windows systems.
     WinRT(windows::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(web::WebHandle),
-
-    Android(android::AndroidHandle),
+    /// A raw window handle for Android NDK.
+    ///
+    /// ## Availability Hints
+    /// This variant is used on Android targets.
+    AndroidNDK(android::AndroidNDKHandle),
 }
 
 /// This wraps a [`RawWindowHandle`] to give it a [`HasRawWindowHandle`] impl.

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() -> OrbitalHandle {
+        OrbitalHandle {
             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() -> UIKitHandle {
+        UIKitHandle {
+            ui_window: ptr::null_mut(),
+            ui_view: ptr::null_mut(),
+            ui_view_controller: ptr::null_mut(),
+        }
+    }
+}

src/unix.rs

@@ -7,7 +7,7 @@ use cty::c_ulong;
 ///
 /// ## Construction
 /// ```
-/// # use raw_window_handle::unix::XlibHandle;
+/// # use raw_window_handle::XlibHandle;
 /// let handle = XlibHandle::empty();
 /// /* set fields */
 /// ```
@@ -24,7 +24,7 @@ pub struct XlibHandle {
 ///
 /// ## Construction
 /// ```
-/// # use raw_window_handle::unix::XcbHandle;
+/// # use raw_window_handle::XcbHandle;
 /// let handle = XcbHandle::empty();
 /// /* set fields */
 /// ```
@@ -41,7 +41,7 @@ pub struct XcbHandle {
 ///
 /// ## Construction
 /// ```
-/// # use raw_window_handle::unix::WaylandHandle;
+/// # use raw_window_handle::WaylandHandle;
 /// let handle = WaylandHandle::empty();
 /// /* set fields */
 /// ```

src/web.rs

@@ -1,17 +1,17 @@
-/// Raw window handle for the web
+/// Raw window handle for the Web.
 ///
 /// ## Construction
 /// ```
-/// # use raw_window_handle::web::WebHandle;
+/// # use raw_window_handle::WebHandle;
 /// let mut handle = WebHandle::empty();
 /// /* set fields */
 /// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct WebHandle {
-    /// An ID value inserted into the data attributes of the canvas element as 'raw-handle'
+    /// An ID value inserted into the data attributes of the canvas element as '`raw-handle`'.
     ///
-    /// When accessing from JS, the attribute will automatically be called rawHandle
+    /// When accessing from JS, the attribute will automatically be called `rawHandle`.
     ///
     /// Each canvas created by the windowing system should be assigned their own unique ID.
     /// 0 should be reserved for invalid / null IDs.