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.
This commit is contained in:
Ryan McGrath 2021-08-09 02:09:08 -07:00
parent 93424f74c0
commit 87533d576f
No known key found for this signature in database
GPG key ID: DA6CBD9233593DEA
10 changed files with 60 additions and 64 deletions

View file

@ -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

View file

@ -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};

View file

@ -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;

View file

@ -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")]

View file

@ -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;

View file

@ -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;

View file

@ -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::<T>(&delegate);
let class = native_interface::register_view_controller_class::<T>(&delegate);
let view = View::with(delegate);
let objc = unsafe {

View file

@ -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<T> View<T> 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<T> {
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 {

View file

@ -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::*;