A cross-platform UI framework for .NET
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
Max Katz 1efe0dfabb
Bump MACOSX_DEPLOYMENT_TARGET to 12.0 (#22633)
3 weeks ago
..
inc Use MicroCom smart pointer wrappers in Avalonia.Native (#22519) 4 weeks ago
src/OSX Bump MACOSX_DEPLOYMENT_TARGET to 12.0 (#22633) 3 weeks ago
Avalonia.Native.macOS.proj Use MicroCom smart pointer wrappers in Avalonia.Native (#22519) 4 weeks ago
README.md Use MicroCom smart pointer wrappers in Avalonia.Native (#22519) 4 weeks ago
generate-headers.sh .NET 11 SDK target + .NET 11 WASM support (#22196) 4 weeks ago

README.md

Avalonia.Native

This project implements the macOS native platform backend for Avalonia using Objective-C++ and COM (Component Object Model) interfaces.

COM Reference Management

This codebase uses COM for cross-boundary object lifetime management. COM types are typically prefixed with IAvn (interfaces) or Avn (implementations). All COM objects ultimately derive from IUnknown and use reference counting (AddRef/Release).

Do not use raw COM pointers. Fields, instance variables, closures, containers, locals and function parameters all use the smart pointer types below. Raw pointers appear only at real boundaries: C exports, untyped void** out-parameters and C callback contexts.

Implementing COM interfaces

avalonia-native.h is generated by MicroCom in smart pointer wrapper mode. Every interface method has a raw impl_* vtable slot and a non-virtual wrapper with ComPtr arguments. Implementations override the ComPtr shaped methods of MicroComImpl<IFoo>:

IDL Override
IFoo* GetFoo() ComPtr<IFoo> GetFoo()
HRESULT GetFoo(IFoo** ppv) HRESULT GetFoo(ComPtr<IFoo>& ppv)
HRESULT SetFoo(IFoo* foo) HRESULT SetFoo(const ComPtr<IFoo>& foo)
no interface types unchanged

The generated impl_* thunk opens an autorelease pool and keeps this and every interface argument alive for the duration of the call. Implementations need no manual call prologue.

Never inherit from a raw interface, only from MicroComImpl<IFoo> (or ComSingleObject<IFoo, &IID_IFoo>, which does it for you). For interfaces in a cpp-virtual-inherits chain (IAvnTopLevel → IAvnWindowBase → IAvnWindow / IAvnPopup), inherit the adapters with virtual in every class. This is a MANDATORY requirement that is needed because with Itanium ABI (followed by clang on mac) we'll have NULL's (or something worse, it's UB) in vtable slots. There is NO compiler warning for this, you'll get a hard crash when attempting to call from C#.

INTERFACE_MAP_ENTRY keeps the interface type, not the adapter: INTERFACE_MAP_ENTRY(IAvnWindow, IID_IAvnWindow).

COM Return Value Convention

Any COM interface reference returned from a COM call has its reference counter incremented. With ComPtr signatures the wrappers handle this. New methods in avn.idl should still prefer the out-parameter pattern:

// Avoid:
IFoo* GetFoo();

// Prefer:
HRESULT GetFoo(IFoo** ppv);

Smart pointer types

Objective-C Objects

For Objective-C objects, reference counting is provided by the compiler. Objective-C pointers look like raw pointers, however every NSObject* reference is properly ref-counted by ARC (Automatic Reference Counting). No manual wrapping is needed for NSObject* fields.

COM Smart Pointer Types

All retained COM references must use one of the following wrappers defined in inc/comimpl.h:

ComPtr<T> — Owning Reference

Use for any COM pointer that the holder needs to keep alive.

ComPtr<IAvnWindow> _window; // correct
IAvnWindow* _window;        // WRONG — raw COM pointer in a field

ComPtr has no implicit conversion to a raw pointer. Pass ComPtr along, and make helper functions and Objective-C methods take const ComPtr<T>& or return ComPtr<T>. Use getRetainedReference() only to hand an owned reference to a raw boundary, such as an untyped void** out-parameter (we currently use those for second COM return due to MicroCOM limitation in few places) or a C export.

Use dynamicCast<T>() to get the C++ implementation behind an interface pointer. It is safe on objects implemented in C#: they yield null. Never use raw dynamic_cast on a COM pointer, because C# objects have no RTTI.

ComObjectWeakPtr<T> — Non-Owning Weak Reference

Use for intentional non-owning references to ComObject-derived objects (internal implementations). Allows safely referencing COM objects without extending their lifetime.

ComObjectWeakPtr<WindowBaseImpl> _parent; // correct
WindowBaseImpl* _parent;                  // WRONG

Access weak references with tryGet(), which returns a ComPtr<T> (null if the object was destroyed):

auto parent = _parent.tryGet();
if (parent) {
    parent->DoSomething();
}

Thread safety

The ComObject reference counter is atomic. C# can release objects from any thread, for example from the GC finalizer or the render thread. tryGet() is safe from any thread: it never returns an object that is in destruction. A single ComPtr or ComObjectWeakPtr instance is not safe for concurrent modification, the same as std::shared_ptr.

ComStaticPtr<T> — Process-Lifetime Static Reference

Use for static/global COM singletons that must live for the entire process lifetime. Intentionally does not Release in its destructor to avoid crashes during app teardown.

static ComStaticPtr<IAvnGlDisplay> GlDisplay; // correct
static IAvnGlDisplay* GlDisplay;              // WRONG

Assign via set(), read via get() or the implicit conversion to ComPtr<T>:

GlDisplay.set(comnew<AvnGlDisplay>());

comnew<T>(args...) — COM Object Factory

A convenience template similar to std::make_shared. Creates a new COM object and returns it wrapped in a ComPtr<T> that owns the initial reference:

ComPtr<Cursor> cursor = comnew<Cursor>(nsCursor);

comself(this) — Reference to the Calling Object

ComPtr has no constructor from a raw pointer. To pass this where a ComPtr or ComObjectWeakPtr is expected, use comself(this). It only accepts ComObject-derived classes:

View = [[AvnView alloc] initWithParent:comself(this)];