cacao/ARCHITECTURE.md

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::wrap(unsafe {
                msg_send![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 {
            (&mut *obj).set_ivar(BACKGROUND_COLOR, color);
        });

        #[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() -> *const Class {
    static mut VIEW_CLASS: *const Class = 0 as *const Class;
    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 fn(&Object, _) -> BOOL);

        decl.add_ivar::<id>(BACKGROUND_COLOR);
    
        VIEW_CLASS = decl.register();
    });

    unsafe { VIEW_CLASS }
}

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) -> *const 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 fn(&Object, _) -> BOOL
        );

        decl.add_method(
            sel!(draggingEntered:),
            dragging_entered::<T> as extern fn (&mut Object, _, _) -> NSUInteger
        );
    })
}

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 fn is_flipped(_: &Object, _: Sel) -> BOOL {
    return YES;
}

Here, we just want to tell NSView to use top,left as the origin point, so we need to respond YES in this subclass method.

extern 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::from_ptr(info) }
    }).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.