* Use objc2 * Replace `objc_id` * Remove sel_impl import * Fix `add_method` calls * Fix accessing raw FFI functions * Fix Encode impl * Fix message sends arguments that do not implement `Encode` * Use immutable reference in a few places where now necessary See https://github.com/madsmtm/objc2/pull/150 for a bit of background * Add a few Send + Sync bounds where examples require it This is something we'll need to look into properly * Use `&'static Class` instead of `*const Class` Safer and more ergonomic. Also required for `msg_send_id!` macro * Use msg_send_id! and rc::Id * Update objc2 to v0.3.0-beta.2 * Replace `BOOL` with `Bool` when declaring delegates This makes cacao compile on Aarch64 again * Remove a few impossible to use correctly `into_inner` functions These consumed `self`, and hence also dropped `Id` variable that was responsible for keeping the returned pointer alive * Remove a few impossible to use correctly `From` implementations * Quickly fix UB with using BACKGROUND_COLOR ivar * Fix double-freeing of windows * Fix double freeing of strings * Fix a few remaining double-frees
17 KiB
Cacao Architecture
Cacao is a library to interface with AppKit (macOS) or UIKit (iOS/iPadOS/tvOS). It uses the Objective-C runtime to handle calling into these frameworks.
Said frameworks typically use an Object Oriented style of programming (subclasses, etc), which can be tricky to handle with the way that Rust works with regards to ownership. Thankfully, AppKit & UIKit often also use a delegate pattern - objects registered to receive callbacks. With some creative assumptions, we can get somewhat close to expected conventions.
This document outlines some of the thinking surrounding the architectural patterns used in this framework. Consider it to be a somewhat living document - things may change or bend as far as rules go, but hopefully this guide makes looking through the framework easier.
In general, a tl;dr:
macOS architecture
App -> Window(s) -> Core Controls
iOS architecture
App -> Window(s) -> UIScene(s) -> Core Controls
Control Setup
A typical control in Cacao has 2-3 main pieces:
- The core control, which can take an optional delegate. More on this below.
- iOS/macOS bridges, which inject a subclass into the Objective-C runtime that forwards methods/callbacks/etc to the Rust side of things.
- Extra delegates, which are similar to the above bridges (some classes need this to avoid issues).
Core Control Contract
A core control is just the Rust interface. It should adhere to the following "contract".
It should always expose an objc
field, which holds the underlying Objective-C object.
This is important, as the underlying frameworks can differ in how they handle things, and they get frequent-ish updates each year. There should always be an escape hatch to make life easier for the end-user.
Controls should always expose the underlying Layer.
This is technically not "correct" on macOS but I don't care. We explicitly expect there to be a layer on controls, and modern macOS wants things to be layer backed anyway.
For example, the View<T>
type has the following field:
Controls should always expose AutoLayout Anchors.
AutoLayout is the preferred layout engine for Apple's frameworks. Users who need frame-based layouts get them for free as
long as the control also implements the Layout
trait.
Interior Mutability makes life easier.
I anticipate this being somewhat divisive, maybe. Not sure. Point is, Rust's model is already hard enough to reason about with UI frameworks - we can try to ease this with interior mutability on controls.
utils::properties::ObjcProperty
is a handy wrapper for this, which should ideally be used - it will handle retain counts while
simultaneously making the borrow model feel "correct" on the Rust side.
Control Example
Let's walk through the View<T>
type to better understand this architecture.
Core Control
Since this is our Rust type, we can mostly jump right in. Let's start with the struct definition:
#[derive(Debug)]
pub struct View<T = ()> {
/// An internal flag for whether an instance of a View<T> is a handle. Typically, there's only
/// one instance that should have this set to `false` - if that one drops, we need to know to
/// do some extra cleanup.
pub is_handle: bool,
/// A pointer to the Objective-C runtime view controller.
pub objc: ObjcProperty,
/// References the underlying layer. This is consistent across macOS, iOS and tvOS - on macOS
/// we explicitly opt in to layer backed views.
pub layer: Layer,
/// A pointer to the delegate for this view.
pub delegate: Option<Box<T>>,
/// A pointer to the Objective-C runtime top layout constraint.
pub top: LayoutAnchorY,
/// A pointer to the Objective-C runtime leading layout constraint.
pub leading: LayoutAnchorX,
/// A pointer to the Objective-C runtime left layout constraint.
pub left: LayoutAnchorX,
/// A pointer to the Objective-C runtime trailing layout constraint.
pub trailing: LayoutAnchorX,
/// A pointer to the Objective-C runtime right layout constraint.
pub right: LayoutAnchorX,
/// A pointer to the Objective-C runtime bottom layout constraint.
pub bottom: LayoutAnchorY,
/// A pointer to the Objective-C runtime width layout constraint.
pub width: LayoutAnchorDimension,
/// A pointer to the Objective-C runtime height layout constraint.
pub height: LayoutAnchorDimension,
/// A pointer to the Objective-C runtime center X layout constraint.
pub center_x: LayoutAnchorX,
/// A pointer to the Objective-C runtime center Y layout constraint.
pub center_y: LayoutAnchorY
}
A few things to note here!
T
is optional.
We want a user to be able to just slap a View
onto the screen if they want - they're essential building blocks, after all. We default
this to ()
and provide a designated initializer (see below) for cases where you want a delegate set.
is_handle
We want to be able to run cleanup on Drop
of the Rust struct, because we want Rust programmers to be able to think in their assumed lifecycle,
not Objective-C's. We need to be able to clone this into a possible delegate to enable customizing as if it were a class, though; enter is_handle
.
Essentially, is_handle
should only be false for the "originating" View
. Clones should always have is_handle
set to true; this guard is checked
on Drop, and if it's false, we know we're dropping the original and can clean up.
objc
This stores the underlying Objective-C object (e.g, NSView
or UIView
).
Layer backing
Controls should expose a layer
property. On macOS this technically should be optional, but I'm making the BDFL decision to enforce it being there, because
outside of a shrinking set of cases, you want it there.
delegate
A delegate
is our Rust trait impl that receives callbacks from the core control.
For instance, you might have a View<DragAndDrop>
that calls are forwarded to. It'd look something like the following:
pub struct DragAndDrop;
impl cacao::view::ViewDelegate for DragAndDrop {
const NAME: &'static str = "DragAndDropView";
fn did_load(&mut self, view: cacao::view::View) {
// Customize View in here, persist it or something
}
// implement various drag and drop handlers
}
And the View<DragAndDrop>
would be constructed like so:
let dnd_view = View::with(DragAndDrop);
AutoLayout Abound
The various Layout Anchors in here are used for AutoLayout (positioning/sizing on the screen). They should always be set.
Default
Not every control needs a Default
impl, but View defaulting is convenient for deep initialization, so we offer it.
impl Default for View {
/// Returns a stock view, for... well, whatever you want.
fn default() -> Self {
View::new()
}
}
Base Initializers
So next on the list is View::new()
. We also have an internal init(view)
method to collect some logic that we need in two places.
register_view_class()
is located in view/macos.rs
on macOS, and view/ios.rs
on iOS; this is a bridge that handles class setup.
We'll look at this more in-depth below, but the general idea here is that the method returns a Class *
that can be used to create a
new Objective-C object.
impl View {
/// An internal initializer method for very common things that we need to do, regardless of
/// what type the end user is creating.
///
/// This handles grabbing autolayout anchor pointers, as well as things related to layering and
/// so on. It returns a generic `View<T>`, which the caller can then customize as needed.
pub(crate) fn init<T>(view: id) -> View<T> {
unsafe {
let _: () = msg_send![view, setTranslatesAutoresizingMaskIntoConstraints:NO];
#[cfg(target_os = "macos")]
let _: () = msg_send![view, setWantsLayer:YES];
}
View {
is_handle: false,
delegate: None,
top: LayoutAnchorY::top(view),
left: LayoutAnchorX::left(view),
leading: LayoutAnchorX::leading(view),
right: LayoutAnchorX::right(view),
trailing: LayoutAnchorX::trailing(view),
bottom: LayoutAnchorY::bottom(view),
width: LayoutAnchorDimension::width(view),
height: LayoutAnchorDimension::height(view),
center_x: LayoutAnchorX::center(view),
center_y: LayoutAnchorY::center(view),
layer: Layer::from_id(unsafe { msg_send_id![view, layer] }),
objc: ObjcProperty::retain(view),
}
}
/// Returns a default `View`, suitable for customizing and displaying.
pub fn new() -> Self {
View::init(unsafe {
msg_send![register_view_class(), new]
})
}
}
Delegate Initializer
For types that accept a delegate, the common pattern we use is for the initializer to be named with()
. Below, we implement with()
for View<T>
:
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 mut delegate = Box::new(delegate);
let view = unsafe {
let view: id = msg_send![class, new];
let ptr = Box::into_raw(delegate);
(&mut *view).set_ivar(VIEW_DELEGATE_PTR, ptr as usize);
delegate = Box::from_raw(ptr);
view
};
let mut view = View::init(view);
(&mut delegate).did_load(view.clone_as_handle());
view.delegate = Some(delegate);
view
}
}
Note that we use a second view class registration function here, as it performs some extra work to ensure that a unique subclass is created per-Rust-type. We dive
into some unsafe
here, as we need to set a pointer to our trait object T
so that the callbacks are able to load and call when coming around from the Objective-C
side - this is explained more in the bridge sections below.
Drawing the Owl
As this block is likely to still grow, we'll be somewhat brief here - below, we implement a clone_as_handle()
method, which returns a bland clone of this type (a handle).
Notably, this does not have a delegate reference, and is_handle
is set to true
. This is passed to the trait implementation in did_load()
, to enable the trait having access
to the containing Objective-C type.
impl<T> View<T> {
/// An internal method that returns a clone of this object, sans references to the delegate or
/// callback pointer. We use this in calling `did_load()` - implementing delegates get a way to
/// reference, customize and use the view but without the trickery of holding pieces of the
/// delegate - the `View` is the only true holder of those.
pub(crate) fn clone_as_handle(&self) -> View {
View {
delegate: None,
is_handle: true,
layer: self.layer.clone(),
top: self.top.clone(),
leading: self.leading.clone(),
left: self.left.clone(),
trailing: self.trailing.clone(),
right: self.right.clone(),
bottom: self.bottom.clone(),
width: self.width.clone(),
height: self.height.clone(),
center_x: self.center_x.clone(),
center_y: self.center_y.clone(),
objc: self.objc.clone()
}
}
/// Call this to set the background color for the backing layer.
pub fn set_background_color<C: AsRef<Color>>(&self, color: C) {
let color: id = color.as_ref().into();
#[cfg(target_os = "macos")]
self.objc.with_mut(|obj| unsafe {
// TODO: Fix this unnecessary retain!
(&mut *obj).set_ivar::<id>(BACKGROUND_COLOR, msg_send![color, retain]);
});
#[cfg(target_os = "ios")]
self.objc.with_mut(|obj| unsafe {
let _: () = msg_send![&*obj, setBackgroundColor:color];
});
}
}
We also see a set_background_color
, which performs different calls depending on the target OS environment: iOS supports background colors by default, and macOS... well, we store it as an ivar
, and then rely on the
layer painting itself in the bridge implementation. You might see some cases online where code simply just does layer.backgroundColor.cgColor = ...
, but this doesn't work properly for dark mode support.
Layout Support
The layout::Layout
trait implements a slew of commonly needed functions, such as setting frames, handling view adding/removing, hiding and showing, and so on. Controls need only implement one or two Layout
trait methods
to get most of this for free:
impl<T> Layout for View<T> {
fn with_backing_node<F: Fn(id)>(&self, handler: F) {
self.objc.with_mut(handler);
}
fn get_from_backing_node<F: Fn(&Object) -> R, R>(&self, handler: F) -> R {
self.objc.get(handler)
}
}
Here, we simply pass handlers into the objc
field calls. With this setup, we're able to offer relatively sound checks for borrowing the underlying types, and most other Layout
methods "just work".
Dropping
Here, we simply check if the dropping item is a handle or not. If it's not (i.e, if it's the top-level original), we can ensure it's removed from the Objective-V view heirarchy and be on our way.
impl<T> Drop for View<T> {
/// If the instance being dropped is _not_ a handle, then we want to go ahead and explicitly
/// remove it from any super views.
///
/// Why do we do this? It's to try and match Rust's ownership model/semantics. If a Rust value
/// drops, it (theoretically) makes sense that the View would drop... and not be visible, etc.
///
/// If you're venturing into unsafe code for the sake of custom behavior via the Objective-C
/// runtime, you can consider flagging your instance as a handle - it will avoid the drop logic here.
fn drop(&mut self) {
if !self.is_handle {
self.remove_from_superview();
}
}
}
Bridges(s)
We'll step through an example (abridged) View
bridge below, for macOS. You should consult the full implementation in view/
to learn more after reading this.
For our basic View
type, we want to just map to the corresponding class on the Objective-C side (in this case, NSView
), and maybe do a bit of tweaking for sanity reasons.
pub(crate) fn register_view_class() -> &'static Class {
static mut VIEW_CLASS: Option<'static Class> = None;
static INIT: Once = Once::new();
INIT.call_once(|| unsafe {
let superclass = class!(NSView);
let mut decl = ClassDecl::new("RSTView", superclass).unwrap();
decl.add_method(sel!(isFlipped), enforce_normalcy as extern "C" fn(_, _) -> _);
decl.add_ivar::<id>(BACKGROUND_COLOR);
VIEW_CLASS = Some(decl.register());
});
unsafe { VIEW_CLASS.unwrap() }
}
This function (called inside View::new()
) creates one reusable View
subclass, and returns the type on subsequent calls. We're able to add methods to it (add_method
) which match
Objective-C method signatures, as well as provision space for variable storage (add_ivar
).
For our delegate types, we need a different class creation method - one that creates a subclass per-unique-type:
pub(crate) fn register_view_class_with_delegate<T: ViewDelegate>(instance: &T) -> &'static Class {
load_or_register_class("NSView", instance.subclass_name(), |decl| unsafe {
decl.add_ivar::<usize>(VIEW_DELEGATE_PTR);
decl.add_ivar::<id>(BACKGROUND_COLOR);
decl.add_method(
sel!(isFlipped),
enforce_normalcy as extern "C" fn(_, _) -> _,
);
decl.add_method(
sel!(draggingEntered:),
dragging_entered::<T> as extern "C" fn (_, _, _) -> _,
);
})
}
Here, we add a method that only makes sense if you're using a delegate (notifying about a drag-enter event). We also provision an extra storage slot, which contains a pointer
to the Rust ViewDelegate
implementation.
The methods we're setting up can range from simple to complex - take isFlipped
:
extern "C" fn is_flipped(_: &Object, _: Sel) -> Bool {
return Bool::YES;
}
Here, we just want to tell NSView
to use top,left as the origin point, so we need to respond Bool::YES
in this subclass method.
extern "C" fn dragging_entered<T: ViewDelegate>(this: &mut Object, _: Sel, info: id) -> NSUInteger {
let view = utils::load::<T>(this, VIEW_DELEGATE_PTR);
view.dragging_entered(DragInfo {
info: unsafe { Id::retain(info).unwrap() }
}).into()
}
This is an example of a more complex method: we load the ViewDelegate
type from the pointer set on the object, and forward the information
into the dragging_entered
trait method.
Conclusion
Hopefully this helps newcomers understand the design choices and architecture found in this repository. It can feel odd at first, but ends up lending itself well to UI patterns, and provides some structure for how things should work.