API — ICoreEssentials/UI/Backends/AppKit

The public contract of 4 header(s) under ICoreEssentials/UI/Backends/AppKit — 1 class/struct definition(s), 0 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICoreAppKitFrameTrace.h#

ICoreEssentials/UI/Backends/AppKit/ICoreAppKitFrameTrace.h

ICORE_APPKIT_FRAME_TRACE -- what one animation frame COSTS on this seat, and how many of them actually arrive (A10.14).

This is the AppKit counterpart of ICORE_WINUI_FRAME_TRACE, built for the same question and after the same owner report: a slide-out panel that reads as a glitch rather than as a slide. The Windows backend's W10.28 answered it on that seat with two numbers nothing else could give --

HOW MANY SAMPLES a 533 ms animation delivered (three), and WHAT EACH ONE COST in frame writes, layout passes and repaints

-- and the pair is what separates "the easing is wrong" from "the frames are not arriving". This seat had neither number: ICORE_PANEL_TRACE logs the call that STARTS a slide and nothing in between.

ICoreAppKitFrameTraceCounts#

ICoreAppKitFrameTrace.h:48 · struct · 0 declaration(s)

struct ICoreAppKitFrameTraceCounts {
public:
    long long frameSets = 0;
    long long geometryChanges = 0;
    long long layoutPasses = 0;
    long long repaints = 0;
};
};

File-scope declarations#

// What a counted site did. Four, because the four answer four different
// questions about the same frame:
// 
// FrameSet       a frame was WRITTEN, whether or not it changed anything
// GeometryChange the write actually moved or resized the view
// LayoutPass     that change re-ran a layout over the view's own subtree
enum class ICoreAppKitFrameTraceEvent {
    FrameSet,
    GeometryChange,
    LayoutPass,
    Repaint,
};

ICoreAppKitMainQueue.h#

ICoreEssentials/UI/Backends/AppKit/ICoreAppKitMainQueue.h

Backend-internal. Not part of any public surface, and no Objective-C in it, so either seat can include it. Peer of ICoreAppKitWake.h.

WHY IT EXISTS -- rows A8.6, §0.104 and §0.155 of this backend's migration notes. (The notes are named by row rather than by file: this banner is reproduced verbatim on a PUBLIC generated API page, and D15 forbids a public page naming a contributor-tree document — §0.161.)

ICoreMainThread::post() used to hand the callable to dispatch_get_main_queue(). That is correct on a bare main thread and WRONG in the one context every regression-suite case actually runs in: inside a main-queue drain. The main queue is a SERIAL queue, so while one of its blocks is on the stack no other block of that queue may start -- and no number of nested run loops changes that, because libdispatch refuses to

Declares no class of its own — see the file.

ICoreAppKitNativeHandleAccess.h#

ICoreEssentials/UI/Backends/AppKit/ICoreAppKitNativeHandleAccess.h

The AppKit-zone twin of UI/ICoreNativeHandleAccess.h: the one place a wrapper's opaque native handle is turned back into something this backend understands.

IMPLEMENTATION SIDE ONLY. Include this from a .mm/.cpp inside UI/Backends/AppKit/ -- never from a wrapper header. Like its Qt twin, every helper tolerates a null wrapper and answers null for it, because parent is optional almost everywhere in this API and making each caller write the check is how one of them eventually forgets.

⚠ THE HANDLE IS AN ICoreAppKitView*, NOT AN NSView*, AND THE DIFFERENCE IS INVISIBLE. Both are void* at the seam and both survive a __bridge cast, so getting this wrong produces no diagnostic at all -- it produces a segfault somewhere else, later. It has already happened once in this tree: A3.5's

Declares no class of its own — see the file.

ICoreAppKitWake.h#

ICoreEssentials/UI/Backends/AppKit/ICoreAppKitWake.h

Backend-internal. Not part of any public surface, and no Objective-C in it, so either seat can include it.

WHY IT EXISTS. ICoreApplication::tick(waitMs) blocks in -nextEventMatchingMask:untilDate:, which wakes for NSEvents and NOTHING ELSE. GCD main-queue work does get SERVICED while it waits -- measured -- but it does not END the wait, so a tick(500) with work already pending still sits out its whole timeout. The header's contract is "sleeps until something happens or that long passes, WHICHEVER COMES FIRST", and Qt honours it because a posted event is an event: processEvents returns as soon as it handles one.

So anything that makes the application have work to do must also post an event, or the two backends disagree about what "something happens" means.

Declares no class of its own — see the file.