From 87533d576f06bdcc004ab51350a16bfdda1f11e7 Mon Sep 17 00:00:00 2001 From: Ryan McGrath Date: Mon, 9 Aug 2021 02:09:08 -0700 Subject: [PATCH] Fix errors when compiling docs. Feature flags that clash are no fun. This reworks a few things so that docs can properly build with all feature flags at once and note their support. Also adds a supported table to the README for ease of discovery. --- README.md | 41 ++++++++++++++++++++++++-------------- build.rs | 2 +- src/image/mod.rs | 8 ++++---- src/input/mod.rs | 8 ++++---- src/lib.rs | 13 ++++++------ src/scrollview/mod.rs | 8 ++++---- src/text/label/mod.rs | 8 ++++---- src/view/controller/mod.rs | 16 ++++----------- src/view/mod.rs | 18 +++++------------ src/webview/mod.rs | 2 +- 10 files changed, 60 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index f19d42a..e7c06f1 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,11 @@ rampant for wrapped controls. This does **not** mean you can't assess, review, o usage - just know it's happening, and in large part it's not going away. Issues pertaining to the mere existence of unsafe will be closed without comment._ +If you're looking to build the docs for this on your local machine, you'll want the following due to the way feature flags work +with `cargo doc`: + +`RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features --open` + # Hello World ```rust @@ -62,22 +67,28 @@ ensures the application has had time to initialize and do any housekeeping neces scenes. ## Currently Supported -In terms of mostly working pieces, the following currently work. This list is not exhaustive and you're encouraged to check out the documentation for more info: +In terms of mostly working pieces, the table below showcases the level of support for varying features. This list is not exhaustive just by virtue of documentation updating being hell - so you're encouraged to check out the code-built documentation for more info: -- `App` initialization and event delegation -- `Window` construction, handling, and event delegation -- `View` construction, basic styling, some event delegation -- `ViewController` construction, lifecycle delegation -- `Color`, for handling system-established color types -- `ListView` support, including cell reuse (still needs testing) -- `Button` support, as well as enabling them in Toolbars -- `Label` and `TextField` support for basic text handling. -- `Image`, `ImageView` and `SystemIcon` for image usage. Images can use a custom draw handler, and draw graphics with the [core_graphics]() crate -- `Toolbar` construction and basic API -- `SplitViewController` support, including some Big-Sur-only additions -- `WebView` with a basic API for handling callbacks -- `UserDefaults` for persisting small pieces of data per-application -- `Autolayout` for View layout and such +Note that while iOS has green checkmarks, some components still aren't as well defined (e.g, Views/ViewControllers are still very alpha there). + +Non-Apple platforms that shim or provide a form of AppKit may be able to use a good chunk of the AppKit support in this library. + +| Component | Description | AppKit | iOS | tvOS | +| ------------------- | ----------------------------------- | ------ | --- | ---- | +| App | Initialization & events | ✅ | ✅ | ❌ | +| Window | Construction, handling, events | ✅ | ✅ | ❌ | +| View | Construction, styling, events | ✅ | ✅ | ❌ | +| ViewController | Construction, lifecycle events | ✅ | ✅ | ❌ | +| Color | System-backed colors, theming | ✅ | ✅ | ❌ | +| ListView | Reusable list w/ cached rows | ✅ | ❌ | ❌ | +| Button | Styling, events, toolbar support | ✅ | ❌ | ❌ | +| Label/TextField | Text rendering & input | ✅ | ❌ | ❌ | +| Image/ImageView | Loading, drawing, etc | ✅ | ❌ | ❌ | +| Toolbar | Basic native toolbar | ✅ | ❌ | ❌ | +| SplitViewController | Split views (Big Sur friendly) | ✅ | ❌ | ❌ | +| WebView | Wrapper for WKWebView | ✅ | ❌ | ❌ | +| UserDefaults | Persisting small data | ✅ | ✅ | ❌ | +| Autolayout | View layout for varying screens | ✅ | ✅ | ❌ | ## Optional Features diff --git a/build.rs b/build.rs index 26896e3..83ec90c 100644 --- a/build.rs +++ b/build.rs @@ -2,7 +2,7 @@ fn main() { println!("cargo:rustc-link-lib=framework=Foundation"); - + #[cfg(feature = "appkit")] println!("cargo:rustc-link-lib=framework=AppKit"); diff --git a/src/image/mod.rs b/src/image/mod.rs index c5d40c0..b916bdf 100644 --- a/src/image/mod.rs +++ b/src/image/mod.rs @@ -16,11 +16,11 @@ mod appkit; #[cfg(feature = "appkit")] use appkit::register_image_view_class; -#[cfg(feature = "uikit")] -mod uikit; +//#[cfg(feature = "uikit")] +//mod uikit; -#[cfg(feature = "uikit")] -use ios::register_image_view_class; +//#[cfg(feature = "uikit")] +//use uikit::register_image_view_class; mod image; pub use image::{Image, DrawConfig, ResizeBehavior}; diff --git a/src/input/mod.rs b/src/input/mod.rs index 24d8764..c937f9d 100644 --- a/src/input/mod.rs +++ b/src/input/mod.rs @@ -59,11 +59,11 @@ mod appkit; #[cfg(feature = "appkit")] use appkit::{register_view_class, register_view_class_with_delegate}; -#[cfg(feature = "uikit")] -mod uikit; +//#[cfg(feature = "uikit")] +//mod uikit; -#[cfg(feature = "uikit")] -use uikit::{register_view_class, register_view_class_with_delegate}; +//#[cfg(feature = "uikit")] +//use uikit::{register_view_class, register_view_class_with_delegate}; mod traits; pub use traits::TextFieldDelegate; diff --git a/src/lib.rs b/src/lib.rs index 4f2ee1a..e3a0f8d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -61,7 +61,6 @@ //! //! - `appkit`: Implements appkit-specific APIs (menus, toolbars, windowing, and so on). //! - `uikit`: Implements uikit-specific APIs (scenes, navigation controllers, and so on). -//! - `tvos`: Implements tvOS-specific APIs. Currently not actually implemented. //! //! The rest of the features in this framework attempt to expose a common API across the three //! aforementioned feature platforms; if you need something else, you can often implement it @@ -72,6 +71,8 @@ //! //! The following are a list of [Cargo features][cargo-features] that can be enabled or disabled. //! +//! - `autolayout`: Enables the use of AutoLayout across all widget types. This is a default +//! feature, but is gated to enable platforms that might shim AppKit without AutoLayout support. //! - `cloudkit`: Links `CloudKit.framework` and provides some wrappers around CloudKit //! functionality. Currently not feature complete. //! - `color_fallbacks`: Provides fallback colors for older systems where `systemColor` types don't @@ -83,7 +84,7 @@ //! code-signed, and will not work without it. //! - `webview`: Links `WebKit.framework` and provides a `WebView` control backed by `WKWebView`. //! This feature will not be supported on tvOS, as the platform has no webview control. -//! - `webview-downloading-appkit`: Enables downloading files from the `WebView` via a private +//! - `webview-downloading-macos`: Enables downloading files from the `WebView` via a private //! interface. This is not an App-Store-safe feature, so be aware of that before enabling. This //! feature is not supported on uikit (a user would handle downloads very differently) or tvOS //! (there's no web browser there at all). @@ -96,15 +97,15 @@ pub use objc; pub use url; pub use lazy_static; -#[cfg(all(feature = "appkit", feature = "uikit", not(feature = "no-intrinsics")))] -compile_error!("The \"appkit\" and \"uikit\" features cannot be enabled together. Pick one. :)"); +//#[cfg(all(feature = "appkit", feature = "uikit", not(feature = "doc_cfg")))] +//compile_error!("The \"appkit\" and \"uikit\" features cannot be enabled together. Pick one. :)"); #[cfg(feature = "appkit")] -#[cfg_attr(docsrs, doc(cfg(target_os = "appkit")))] +#[cfg_attr(docsrs, doc(cfg(feature = "appkit")))] pub mod appkit; #[cfg(feature = "uikit")] -#[cfg_attr(docsrs, doc(cfg(target_os = "uikit")))] +#[cfg_attr(docsrs, doc(cfg(feature = "uikit")))] pub mod uikit; #[cfg(feature = "appkit")] diff --git a/src/scrollview/mod.rs b/src/scrollview/mod.rs index ea39bc8..f2c99af 100644 --- a/src/scrollview/mod.rs +++ b/src/scrollview/mod.rs @@ -61,11 +61,11 @@ mod appkit; #[cfg(feature = "appkit")] use appkit::{register_scrollview_class, register_scrollview_class_with_delegate}; -#[cfg(feature = "uikit")] -mod ios; +//#[cfg(feature = "uikit")] +//mod ios; -#[cfg(feature = "uikit")] -use ios::{register_view_class, register_view_class_with_delegate}; +//#[cfg(feature = "uikit")] +//use ios::{register_view_class, register_view_class_with_delegate}; mod traits; pub use traits::ScrollViewDelegate; diff --git a/src/text/label/mod.rs b/src/text/label/mod.rs index 251325f..aaf8982 100644 --- a/src/text/label/mod.rs +++ b/src/text/label/mod.rs @@ -59,11 +59,11 @@ mod appkit; #[cfg(feature = "appkit")] use appkit::{register_view_class, register_view_class_with_delegate}; -#[cfg(feature = "uikit")] -mod uikit; +//#[cfg(feature = "uikit")] +//mod uikit; -#[cfg(feature = "uikit")] -use uikit::{register_view_class, register_view_class_with_delegate}; +//#[cfg(feature = "uikit")] +//use uikit::{register_view_class, register_view_class_with_delegate}; mod traits; pub use traits::LabelDelegate; diff --git a/src/view/controller/mod.rs b/src/view/controller/mod.rs index 871bb7d..418a18a 100644 --- a/src/view/controller/mod.rs +++ b/src/view/controller/mod.rs @@ -7,17 +7,9 @@ use crate::layout::Layout; use crate::view::{VIEW_DELEGATE_PTR, View, ViewDelegate}; use crate::utils::Controller; -#[cfg(feature = "appkit")] -mod appkit; - -#[cfg(feature = "appkit")] -use appkit::register_view_controller_class; - -#[cfg(feature = "uikit")] -mod uikit; - -#[cfg(feature = "uikit")] -use uikit::register_view_controller_class; +#[cfg_attr(feature = "appkit", path = "appkit.rs")] +#[cfg_attr(feature = "uikit", path = "uikit.rs")] +mod native_interface; /// A `ViewController` is a wrapper around `NSViewController` in AppKit, and `UIViewController` in /// UIKit @@ -52,7 +44,7 @@ where { /// Creates and returns a new `ViewController` with the provided `delegate`. pub fn new(delegate: T) -> Self { - let class = register_view_controller_class::(&delegate); + let class = native_interface::register_view_controller_class::(&delegate); let view = View::with(delegate); let objc = unsafe { diff --git a/src/view/mod.rs b/src/view/mod.rs index c38fc8b..8d95b64 100644 --- a/src/view/mod.rs +++ b/src/view/mod.rs @@ -56,17 +56,9 @@ use crate::layout::{LayoutAnchorX, LayoutAnchorY, LayoutAnchorDimension}; #[cfg(feature = "appkit")] use crate::pasteboard::PasteboardType; -#[cfg(feature = "appkit")] -mod appkit; - -#[cfg(feature = "appkit")] -use appkit::{register_view_class, register_view_class_with_delegate}; - -#[cfg(feature = "uikit")] -mod uikit; - -#[cfg(feature = "uikit")] -use uikit::{register_view_class, register_view_class_with_delegate}; +#[cfg_attr(feature = "appkit", path = "appkit.rs")] +#[cfg_attr(feature = "uikit", path = "uikit.rs")] +mod native_interface; mod controller; pub use controller::ViewController; @@ -211,7 +203,7 @@ impl View { /// Returns a default `View`, suitable for customizing and displaying. pub fn new() -> Self { View::init(unsafe { - msg_send![register_view_class(), new] + msg_send![native_interface::register_view_class(), new] }) } } @@ -220,7 +212,7 @@ impl View where T: ViewDelegate + 'static { /// Initializes a new View with a given `ViewDelegate`. This enables you to respond to events /// and customize the view as a module, similar to class-based systems. pub fn with(delegate: T) -> View { - let class = register_view_class_with_delegate(&delegate); + let class = native_interface::register_view_class_with_delegate(&delegate); let mut delegate = Box::new(delegate); let view = unsafe { diff --git a/src/webview/mod.rs b/src/webview/mod.rs index 1be9e62..ab27ad1 100644 --- a/src/webview/mod.rs +++ b/src/webview/mod.rs @@ -26,7 +26,7 @@ use crate::layer::Layer; use crate::utils::properties::ObjcProperty; #[cfg(feature = "autolayout")] -use crate::layout::LayoutAnchorX, LayoutAnchorY, LayoutAnchorDimension}; +use crate::layout::{LayoutAnchorX, LayoutAnchorY, LayoutAnchorDimension}; mod actions; pub use actions::*;