API — ICoreEssentials/UI/Backends/UIKit

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

ICoreUIKitMainQueue.h#

ICoreEssentials/UI/Backends/UIKit/ICoreUIKitMainQueue.h

Backend-internal. Not part of any public surface, and no Objective-C in it, so every seat in this zone can include it. The UIKit twin of the AppKit backend's main-queue header, and the reasons are the same ones: that header carries them in full and they are not repeated here.

ICoreMainThread::post() lands on a queue this backend OWNS, delivered by a CFRunLoopSource in the common modes -- never on dispatch_get_main_queue(), whose serial-queue guard refuses to re-enter its own drain, so a nested pump inside a main-queue block would deliver nothing.

⚠ ONE DIFFERENCE FROM AppKit, AND IT SHAPES EVERY SIGNATURE BELOW. AppKit's tick() blocks in -nextEventMatchingMask:, which only an NSEvent ends, so that backend posts a wake EVENT. UIKit has no public event pump at all: the loop this backend turns is the CFRunLoop itself, and a CFRunLoopRunInMode call

Declares no class of its own — see the file.

ICoreUIKitScenes.h#

ICoreEssentials/UI/Backends/UIKit/ICoreUIKitScenes.h

Backend-internal. Not part of any public surface, and no Objective-C in it: a scene travels as void* and is a UIWindowScene* on the far side.

iPadOS gives an application SCENES, not windows. The application seat owns the delegates UIKit reports them to, and the window seat is what gives them meaning, so the two meet here and neither links the other: an application with no ICoreWindow in it (a headless run, the application seat's own verify) has no listener, and nothing here needs one.

⚠ A DISCONNECT IS NOT A CLOSE. iPadOS disconnects a background scene to reclaim memory and reconnects the SAME session later, with a new scene object, when the user returns to it. A window that treated a disconnect as a close would lose its content to a memory warning. The user's close is the session being DISCARDED, and that arrives separately.

ICoreUIKitSceneListener#

ICoreUIKitScenes.h:21 · struct · 4 declaration(s)

struct ICoreUIKitSceneListener {
public:
    // A UIWindowScene connected: a new session, or an old one coming back.
    void (*connected)(void* windowScene) = nullptr;
    // It disconnected. Its session may come back as another scene object.
    void (*disconnected)(void* windowScene) = nullptr;
    // Foreground-active, foreground-inactive or background changed.
    void (*activationChanged)(void* windowScene) = nullptr;
    // The user (or the application) destroyed this session: the close.
    void (*sessionDiscarded)(const std::string& persistentIdentifier) = nullptr;
};
};

ICoreUIKitEventMap.h#

ICoreEssentials/UI/Backends/UIKit/Events/ICoreUIKitEventMap.h

UIKit's key and modifier vocabulary, turned into ICore's. The AppKit backend's ICoreAppKitEventMap.h is the model, and its two rules hold here:

• A POSITIONAL CODE FIRST, A CHARACTER SECOND. -[UIKey keyCode] is a USB

HID usage: layout-independent, and it names the keys that type nothing (arrows, Return, the F keys). Anything it does not name is asked of the unmodified character instead.

• THE COMMAND / CONTROL SWAP. ⌘ is ICore's Control and ⌃ is its Meta, as on

macOS and as in Qt, so Ctrl+C in portable code is ⌘C on a Magic Keyboard.

Plain numbers in, so no header here names a UIKit type.

Declares no class of its own — see the file.

ICoreUIKitTouchRouter.h#

ICoreEssentials/UI/Backends/UIKit/Events/ICoreUIKitTouchRouter.h

ICoreUIKitTouchSample#

ICoreUIKitTouchRouter.h:60 · struct · 0 declaration(s)

ICoreUIKitTouchRouter -- where a finger, a pencil or a trackpad click on an iPad goes: to a touch seat, to the gesture recogniser, or down the mouse path to a widget's hooks.

struct ICoreUIKitTouchSample {
public:
    ICoreTouchPhase phase = ICoreTouchPhase::Began;   // Began, Moved, Ended or Cancelled
    std::int64_t touchId = 0;                         // stable for the touch's life
    ICorePointerKind kind = ICorePointerKind::Touch;  // Mouse for a trackpad or mouse
    double screenX = 0.0;                             // UIScreen.coordinateSpace, points
    double screenY = 0.0;
    double pressure = 1.0;                            // 0..1 for a pencil; 1 for a finger
    int tapCount = 1;
    ICoreMouseButton button = ICoreMouseButton::Left; // what an indirect pointer pressed
    ICoreKeyModifiers modifiers = 0;
    double timeMs = 0.0;
};
};

ICoreUIKitTouchRouter#

ICoreUIKitTouchRouter.h:73 · class · pImpl · 11 declaration(s)

class ICoreUIKitTouchRouter {
public:
    // "Call tick() in `delayMs`"; a negative delay withdraws the request.
    using TimerFn = std::function<void(double delayMs)>;
    // Show `text` as a tooltip anchored at a screen point; empty text hides it.
    using ToolTipFn = std::function<void(const std::string& text, double screenX, double screenY)>;

    ICoreUIKitTouchRouter(TimerFn timer, ToolTipFn toolTip);
    ~ICoreUIKitTouchRouter();
    ICoreUIKitTouchRouter(const ICoreUIKitTouchRouter&) = delete;
    ICoreUIKitTouchRouter& operator=(const ICoreUIKitTouchRouter&) = delete;

    // One contact's event. `hit` is the seat UIKit hit-tested the touch to when
    // it began (null for a view no seat owns); it is read only on a contact's
    // Began.
    void touch(ICoreUIKitView* hit, const ICoreUIKitTouchSample& sample);

    // A trackpad pointer entering or leaving `view`. Each view reports its
    // own, so a parent stays entered while the pointer is over its child --
    // Qt's rule, and what UIKit's per-view hover recognisers give.
    void hoverCrossing(ICoreUIKitView* view, bool inside);

    // A trackpad pointer moving over `over` -- the deepest view under it --
    // with no button down. Delivered as a buttonless move, which the widget
    // hears only under setMouseTracking(true).
    void hoverMove(ICoreUIKitView* over, double screenX, double screenY, ICoreKeyModifiers modifiers);

    // A scroll over `over`, in points (positive y: the content moves down).
    // Offered to `over` and then each seat above it until one takes it.
    bool wheel(ICoreUIKitView* over, double screenX, double screenY, double deltaX, double deltaY,
               ICoreKeyModifiers modifiers);

    // The timer asked for through TimerFn has fired.
    void tick(double nowMs);

    // Forget everything in flight without delivering it: the window went away.
    void reset();

    // Test seams.
    [[nodiscard]] bool sequenceInProgress() const;
    [[nodiscard]] int contactCountForTest() const;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreUIKitGraphicsView.h#

ICoreEssentials/UI/Backends/UIKit/Graphics/ICoreUIKitGraphicsView.h

The UIKit backend's graphics tier: the web backend's scene view, carried onto a UIKit seat and the CoreGraphics painter; the web file was ported from UI/Backends/Gtk4/Graphics/ICoreGtk4GraphicsView.h, whose comments are the reasons for this one's behaviour (one fact, one place). A behaviour change belongs in all three.

One ICoreUIKitView shows one scene: the portable ICoreSceneCore decides what is drawn where and what a pointer hits, and this class turns the seat's paint and pointer hooks into those calls. The view transform is a zoom and a scroll. A proxy widget's view is an OVERLAY: a real UIView placed over its item and scaled with the zoom, so it stays a native, hittable view.

ICoreUIKitViewBackdrop#

ICoreUIKitGraphicsView.h:27 · struct · 0 declaration(s)

struct ICoreUIKitViewBackdrop {
public:
    double red = 0.0, green = 0.0, blue = 0.0, alpha = 0.0;
};
};

ICoreUIKitGraphicsView#

ICoreUIKitGraphicsView.h:31 · class · pImpl · 59 declaration(s)

class ICoreUIKitGraphicsView {
public:
    ICoreUIKitGraphicsView();
    ~ICoreUIKitGraphicsView();

    ICoreUIKitGraphicsView(const ICoreUIKitGraphicsView&) = delete;
    ICoreUIKitGraphicsView& operator=(const ICoreUIKitGraphicsView&) = delete;

    ICoreUIKitView& area();
    const ICoreUIKitView& area() const;

    void setScene(ICoreUIKitItemScene* scene);
    [[nodiscard]] ICoreUIKitItemScene* scene() const;

    void setZoom(double zoom);
    [[nodiscard]] double zoom() const;
    void scaleBy(double factor);
    void scaleByAnchoredAt(double factor, double viewX, double viewY);
    void setZoomAnchoredUnderPointer(bool anchored);
    [[nodiscard]] bool isZoomAnchoredUnderPointer() const;
    [[nodiscard]] bool lastPointerViewPos(double& viewX, double& viewY) const;

    void setScroll(double x, double y);
    [[nodiscard]] double horizontalScroll() const;
    [[nodiscard]] double verticalScroll() const;
    void scrollRange(double& minX, double& maxX, double& minY, double& maxY) const;

    [[nodiscard]] ICoreSceneTransform viewTransform() const;
    [[nodiscard]] ICoreScenePoint mapToScene(double viewX, double viewY) const;
    [[nodiscard]] ICoreScenePoint mapFromScene(const ICoreScenePoint& scenePoint) const;
    [[nodiscard]] ICoreSceneRect mapToScene(const ICoreSceneRect& viewRect) const;
    [[nodiscard]] ICoreSceneRect mapFromScene(const ICoreSceneRect& sceneRect) const;
    void centerOn(const ICoreScenePoint& scenePoint);
    void viewportSize(double& width, double& height) const;

    void setAntialiased(bool antialiased);
    [[nodiscard]] bool isAntialiased() const;
    void setBackdrop(const ICoreUIKitViewBackdrop& backdrop);
    [[nodiscard]] ICoreUIKitViewBackdrop backdrop() const;

    // Paints the backdrop and every item that meets `damagedViewRect` (view
    // coordinates; empty means the whole view). Returns how many items drew.
    int draw(ICorePainter& painter, double width, double height) const;
    int draw(ICorePainter& painter, const ICoreSceneRect& damagedViewRect) const;
    void drawOrderForViewRect(const ICoreSceneRect& damagedViewRect,
                              std::vector<ICoreSceneDrawCommand>& out) const;

    // A proxy widget's seat, shown over `item`: framed to the item's box and
    // scaled by the zoom (uniform scale only; a rotated item places its control
    // unrotated). The seat is borrowed -- the proxy owns its widget.
    void setItemOverlay(const ICoreSceneItemId& item, ICoreUIKitView* control);
    void removeItemOverlay(const ICoreSceneItemId& item);
    [[nodiscard]] int overlayCount() const;
    void syncOverlays();
    static void setOverlayResolveHook(std::function<void()> hook);
    bool overlayPlacementForTest(const ICoreSceneItemId& item, ICoreSceneRect& frame, bool& shown) const;
    bool overlayScaleForTest(const ICoreSceneItemId& item, double& scale) const;

    static ICoreUIKitGraphicsView* viewShowing(const ICoreUIKitItemScene* scene);
    static bool isLive(const ICoreUIKitGraphicsView* view);

    int flushDirtyRegion();
    [[nodiscard]] int flushCountForTest() const;
    [[nodiscard]] double dirtyFringeInViewPixels() const;

    // Pointer input in view coordinates. The seat's hooks call these; a probe
    // may call them directly.
    void deliverMouseMove(double viewX, double viewY, ICoreMouseButtons buttons, ICoreKeyModifiers modifiers);
    void deliverMousePress(double viewX, double viewY, ICoreMouseButton button, ICoreKeyModifiers modifiers,
                           int pressCount);
    void deliverMouseRelease(double viewX, double viewY, ICoreMouseButton button, ICoreKeyModifiers modifiers);
    // A scroll in POINTS, positive y moving the content down (the seat's
    // convention); zooms instead when wheelZooms() and no modifier is held.
    void deliverWheel(double viewX, double viewY, double deltaX, double deltaY, ICoreKeyModifiers modifiers);
    void deliverPointerLeft();
    // A mouse gesture the system took away: the scene's grab is released.
    void deliverPointerCancelled();

    void setWheelZooms(bool zooms);
    [[nodiscard]] bool wheelZooms() const;

    void setHoverChangedHook(std::function<void(const ICoreSceneHoverChange&)> hook);
    void setPressedHook(std::function<void(const ICoreScenePressResult&, const ICoreScenePoint&)> hook);
    void setDraggedHook(std::function<void(const ICoreSceneDragResult&, const ICoreScenePoint&)> hook);
    void setReleasedHook(std::function<void(const ICoreSceneReleaseResult&, const ICoreScenePoint&)> hook);

    [[nodiscard]] int itemsPaintedForTest() const;
    void resetItemsPaintedForTest();
    [[nodiscard]] int pointerEventsDeliveredForTest() const;
    void resetPointerEventsDeliveredForTest();

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreUIKitItemAccess.h#

ICoreEssentials/UI/Backends/UIKit/Graphics/ICoreUIKitItemAccess.h

The UIKit backend's graphics tier: the web backend's, carried onto a UIKit seat and the CoreGraphics painter; the web file was ported from UI/Backends/Gtk4/Graphics/ICoreGtk4ItemAccess.h, whose comments are the reasons for this one's behaviour (one fact, one place). A behaviour change belongs in all three.

Declares no class of its own — see the file.

ICoreUIKitItemScene.h#

ICoreEssentials/UI/Backends/UIKit/Graphics/ICoreUIKitItemScene.h

The UIKit backend's graphics tier: the web backend's, carried onto a UIKit seat and the CoreGraphics painter; the web file was ported from UI/Backends/Gtk4/Graphics/ICoreGtk4ItemScene.h, whose comments are the reasons for this one's behaviour (one fact, one place). A behaviour change belongs in all three.

ICoreUIKitItemVisual#

ICoreUIKitItemScene.h:20 · struct · 0 declaration(s)

struct ICoreUIKitItemVisual {
public:
    bool hasFill = false;
    int fillR = 0, fillG = 0, fillB = 0, fillA = 255;

    bool hasBorder = false;
    int borderR = 0, borderG = 0, borderB = 0, borderA = 255;

    double borderWidth = 2.0;
    double cornerRadius = 5.0;
};
};

ICoreUIKitItemScene#

ICoreUIKitItemScene.h:35 · class · pImpl · 15 declaration(s)

class ICoreUIKitItemScene {
public:
    ICoreUIKitItemScene();
    ~ICoreUIKitItemScene();

    ICoreUIKitItemScene(const ICoreUIKitItemScene&) = delete;
    ICoreUIKitItemScene& operator=(const ICoreUIKitItemScene&) = delete;

    ICoreScene& scene();
    const ICoreScene& scene() const;

    void bind(const ICoreSceneItemId& id,
              ICoreUIKitItemVisualFn visual,
              ICoreUIKitItemContentFn content);

    void unbind(const ICoreSceneItemId& id);
    bool isBound(const ICoreSceneItemId& id) const;
    unsigned int boundCount() const;

    void reconcileBounds();

    // Paints every visible item, in draw order, with the painter's current
    // transform as the scene's own space. Returns how many were drawn.
    int draw(ICorePainter& painter) const;

    // Paints one item: the command's clip (in the painter's current space),
    // then its transform -- decomposed into a translation, a rotation and a
    // uniform scale, the only transforms this tree gives an item -- then the
    // body and the content hook. The painter is left as it was found.
    bool drawCommand(const ICoreSceneDrawCommand& command, ICorePainter& painter) const;

    void setDamagedHook(std::function<void()> hook);
    void notifyDamaged() const;

    [[nodiscard]] std::weak_ptr<const int> lifetime() const;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

File-scope declarations#

using ICoreUIKitItemVisualFn = std::function<ICoreUIKitItemVisual()>;

using ICoreUIKitItemContentFn = std::function<void(ICorePainter&)>;

ICoreUIKitSceneNode.h#

ICoreEssentials/UI/Backends/UIKit/Graphics/ICoreUIKitSceneNode.h

The UIKit backend's graphics tier: the web backend's, carried onto a UIKit seat and the CoreGraphics painter; the web file was ported from UI/Backends/Gtk4/Graphics/ICoreGtk4SceneNode.h, whose comments are the reasons for this one's behaviour (one fact, one place). A behaviour change belongs in all three.

ICoreUIKitScenePointerEvent#

ICoreUIKitSceneNode.h:32 · struct · 0 declaration(s)

struct ICoreUIKitScenePointerEvent {
public:
    ICoreUIKitScenePointerKind kind = ICoreUIKitScenePointerKind::Pressed;

    ICoreScenePoint scenePoint;    // ICoreMouseEvent::scenePos
    ICoreScenePoint itemPoint;     // the item's OWN coordinates -- ::pos
    ICoreScenePoint globalPoint;   // toplevel space, this backend's "screen"

    ICoreMouseButton button = ICoreMouseButton::None;
    ICoreMouseButtons buttons = 0;
    ICoreKeyModifiers modifiers = 0;

    double deltaX = 0.0;
    double deltaY = 0.0;
};
};

ICoreUIKitSceneNode#

ICoreUIKitSceneNode.h:47 · struct · 18 declaration(s)

struct ICoreUIKitSceneNode {
public:
    ICoreUIKitSceneNode() = default;
    virtual ~ICoreUIKitSceneNode();

    ICoreUIKitSceneNode(const ICoreUIKitSceneNode&) = delete;
    ICoreUIKitSceneNode& operator=(const ICoreUIKitSceneNode&) = delete;

    ICoreUIKitItemScene* host = nullptr;
    ICoreSceneItemId id;

    ICoreSignalScope themeScope;

    ICoreUIKitSceneNode* parent = nullptr;
    std::vector<ICoreUIKitSceneNode*> children;

    void attachTo(ICoreUIKitItemScene* newHost, ICoreUIKitSceneNode* parentNode);

    void detachFromScene();
    void detachSubtree();

    void detachFromParent();

    void setParentNode(ICoreUIKitSceneNode* newParent);

    void teardownNode();

    virtual ICoreGraphicsObject* asGraphicsObject();

    virtual ICoreGraphicsText* asGraphicsText();

    virtual bool cursorShape(ICoreCursorShape& shapeOut) const;

    virtual bool deliverPointerEvent(const ICoreUIKitScenePointerEvent& event);

    virtual void reconcileBounds();

    void markDirty();

protected:
    virtual void pushAll() = 0;

    virtual void bindSelf() = 0;
};
};

File-scope declarations#

enum class ICoreUIKitScenePointerKind {
    Pressed,
    Moved,           // a move with a grab open -- ICoreGraphicsObject::mouseMoved
    Released,
    DoubleClicked,
    PointerEntered,
    PointerMoved,    // a HOVER move over the item already hovered
    PointerLeft,

    WheelScrolled
};

ICoreUIKitSceneRender.h#

ICoreEssentials/UI/Backends/UIKit/Graphics/ICoreUIKitSceneRender.h

The UIKit backend's graphics tier: the web backend's, carried onto a UIKit seat and the CoreGraphics painter; the web file was ported from UI/Backends/Gtk4/Graphics/ICoreGtk4SceneRender.h, whose comments are the reasons for this one's behaviour (one fact, one place). A behaviour change belongs in all three.

Declares no class of its own — see the file.

ICoreUIKitLayoutAccess.h#

ICoreEssentials/UI/Backends/UIKit/Layouts/ICoreUIKitLayoutAccess.h

What the UIKit backend answers for the layout tier. Every decision -- which frame, what a spacer absorbs, when to re-run -- is ICoreLayoutSeatCore's; this is the translation to a seat (UIKit/Widgets/ICoreUIKitView.h). The gtk4 and WinUI accesses are the same shape, and their banners carry the measurements behind each answer.

Declares no class of its own — see the file.

ICoreUIKitMenuBar.h#

ICoreEssentials/UI/Backends/UIKit/MenuBar/ICoreUIKitMenuBar.h

ICoreUIKitMenuBar#

ICoreUIKitMenuBar.h:55 · class · 20 declaration(s)

The iPadOS main menu, as the menu-mirror seam's other side (UI/MenuBar/ICoreMenuMirror.h, UI/MenuBar/ICoreMenuSystemBar.h).

class ICoreUIKitMenuBar {
public:
    static void* createMenuBar();
    static void releaseMenuBar(void* bar);
    // A top-level menu on `bar`. Returns the menu to fill.
    static void* addTopLevelMenu(void* bar, const std::string& title);

    // A row. `chord` 0 for none. *outInstalledAsAccelerator is false when the
    // chord is refused: not writable as a key command, or already on another
    // row of this bar (UIKit answers only one; the caller's shortcut registry
    // takes it instead).
    static void* addItem(void* menu, const std::string& text, std::uint32_t chord,
                         std::function<void()> onActivated, bool* outInstalledAsAccelerator);
    static void* addSeparator(void* menu);
    static void* addCaption(void* menu, const std::string& text);
    // Turns `item`, already on `menu`, into the row that opens a new menu, and
    // returns that menu.
    static void* attachSubMenu(void* menu, void* item, const std::string& text);
    static void clearMenu(void* menu);
    static void setMenuAboutToShowHook(void* menu, std::function<void()> hook);

    static void setItemText(void* item, const std::string& text);
    static void setItemEnabled(void* item, bool enabled);
    static void setItemCheckable(void* item, bool checkable);
    static void setItemChecked(void* item, bool checked);
    [[nodiscard]] static bool isItemChecked(void* item);

    // The seam's discriminator: the chord carries a modifier or is F1-F12, and
    // it can be written as a key command -- Shift with a printable non-letter
    // is refused, as on AppKit, because only the keyboard layout knows what
    // that key types.
    [[nodiscard]] static bool chordIsSafeAsKeyCommand(std::uint32_t chord);

    // Whether the first responder is a text entry being typed into.
    [[nodiscard]] static bool focusIsInTextEntry();

    // -- test seams ------------------------------------------------------------
    // Builds run since the process started.
    [[nodiscard]] static int buildCountForTest();
    // What the last build could not do (an exception UIKit raised), or empty.
    [[nodiscard]] static std::string lastBuildErrorForTest();
    // The system action a row took its chord from, or empty.
    [[nodiscard]] static std::string itemFallbackForTest(void* item);
    // The key command input and UIKit modifier flags a chord is written as;
    // false when it cannot be.
    static bool chordToKeyCommandForTest(std::uint32_t chord, std::string& input, long long& flags);
};
};

ICoreUIKitMotionDriver.h#

ICoreEssentials/UI/Backends/UIKit/Motion/ICoreUIKitMotionDriver.h

ICoreUIKitMotionDriver#

ICoreUIKitMotionDriver.h:24 · class · pImpl · 10 declaration(s)

Where the UIKit backend's animation ticks come from (tablet port, TB2.22) -- the web driver's surface (Backends/Web/Motion/ICoreWebMotionDriver.h), so the copied runtime calls it unchanged.

class ICoreUIKitMotionDriver {
public:
    using Tick = std::function<void(long long nowMs)>;

    ICoreUIKitMotionDriver();
    ~ICoreUIKitMotionDriver();
    ICoreUIKitMotionDriver(const ICoreUIKitMotionDriver&) = delete;
    ICoreUIKitMotionDriver& operator=(const ICoreUIKitMotionDriver&) = delete;

    void setTick(Tick tick);
    void start();
    void stop();
    [[nodiscard]] bool isRunning() const;
    [[nodiscard]] long long nowMs() const;

    enum class Source { None, FrameClock, Timeout };
    [[nodiscard]] Source source() const;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreUIKitMotionOwners.h#

ICoreEssentials/UI/Backends/UIKit/Motion/ICoreUIKitMotionOwners.h

Tablet port, TB2.22: the UIKit twin of the web owners header.

Which widget an animation belongs to, so the animation stops when its widget dies (web backend, WB7.1). The surface and the rules are UI/Backends/Gtk4/Motion/ICoreGtk4MotionOwners.h's, which keeps the reasoning; the web version watches ICoreWebNode rather than a GtkWidget's "destroy".

Backend-private: nothing outside UI/Backends/Web/ includes it.

Declares no class of its own — see the file.

ICoreUIKitMotionRuntime.h#

ICoreEssentials/UI/Backends/UIKit/Motion/ICoreUIKitMotionRuntime.h

Tablet port, TB2.22: the UIKit twin of Backends/Web/Motion/ ICoreWebMotionRuntime.h, renamed; its driver is the CADisplayLink one.

The web seat's copy of UI/Backends/Gtk4/Motion/ICoreGtk4MotionRuntime.h (web backend, WB7.1), with the backend renamed: it names no toolkit, so its rules and their reasoning are the original's, which stays the authority. What is new on the web is only the driver underneath (ICoreUIKitMotionDriver: the browser's requestAnimationFrame).

File-scope declarations#

// Tablet port, TB2.22: the UIKit twin of Backends/Web/Motion/
// ICoreWebMotionRuntime.h, renamed; its driver is the CADisplayLink one.
// 
// The web seat's copy of UI/Backends/Gtk4/Motion/ICoreGtk4MotionRuntime.h (web backend,
// WB7.1), with the backend renamed: it names no
// toolkit, so its rules and their reasoning are the original's, which stays the
using ICoreUIKitMotionHook = std::function<void(const ICoreAnimationSample& sample)>;

ICoreUIKitLifecycleAccess.h#

ICoreEssentials/UI/Backends/UIKit/System/ICoreUIKitLifecycleAccess.h

For the scene delegate (ICoreUIKitApplication.mm), whose -stateRestorationActivityForScene: is the one place iPadOS asks for a scene's state (tablet port, TB2.18). A header in this zone names no Objective-C type, hence void*.

A +1 NSUserActivity carrying the restoration provider's string, or nullptr when there is no provider or it answered empty. Hand it to ARC with __bridge_transfer (or CFBridgingRelease).

Declares no class of its own — see the file.

ICoreUIKitMenuHook.h#

ICoreEssentials/UI/Backends/UIKit/System/ICoreUIKitMenuHook.h

The application's main menu on iPadOS: the menu bar a user pulls down from the top of the screen, and the list a held Command key shows.

UIKit builds that menu by asking the responder chain, and the application delegate's -buildMenuWithBuilder: is where an application adds to it. The delegate lives with the application seat (ICoreUIKitApplication.mm); what goes INTO the menu is the menu-bar seat's (UIKit/MenuBar/), so the delegate calls this one hook after UIKit's own menus are in place, and the seat is the only code that names what it builds.

builder is the id<UIMenuBuilder> UIKit handed the delegate, bridged to void* because this header names no Objective-C type. It is valid only for the duration of the call. One hook; setting another replaces it, and an empty function removes it. UI thread only.

Declares no class of its own — see the file.

ICoreUIKitCursorAccess.h#

ICoreEssentials/UI/Backends/UIKit/Values/ICoreUIKitCursorAccess.h

What the UIKit seat keeps in an ICoreCursor, for the backend files that apply one (TB2.6's pointer interaction). Nothing outside UI/Backends/UIKit/ includes this.

Declares no class of its own — see the file.

ICoreUIKitIconAccess.h#

ICoreEssentials/UI/Backends/UIKit/Values/ICoreUIKitIconAccess.h

For the themed-icon seat (Icons/ICoreUIKitThemedIcon.cpp, TB2.16): an icon that keeps its vector drawing and re-rasterises at each requested size, with an optional tint flooded over it. The web seat's ICoreWebIconAccess.h with the backend name changed. An invalid tint means none.

Declares no class of its own — see the file.

ICoreUIKitAccessibility.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitAccessibility.h

The accessibility floor for the UIKit backend: what VoiceOver is told about the painted controls.

⚠ THE SURFACE IS THE WEB FLOOR'S (UI/Backends/Web/Widgets/ ICoreWebAccessibility.h), which is GTK4's with the toolkit taken out, so a seat ported from the web keeps its accessibility calls line for line with Web read as UIKit. The reasons for each rule a caller follows are in those headers and are not repeated here.

WHY THIS IS SIMPLER THAN THE WEB'S. A painted control on this backend is already a UIView, and a UIView is an accessibility element when it says so. So there is no mirror: each call writes a record kept beside the view, and the view's own UIAccessibility getters (UIKit/Widgets/ICoreUIKitView.mm) ask this floor at the moment VoiceOver reads them. A relation to a partner that

File-scope declarations#

enum class ICoreUIKitAccessibleRole {
    Presentation,
    Generic,        // the default of every view, and not an element
    Group,
    Button,
    CheckBox,
    Radio,
    Switch,
    Label,
    TextBox,
    SearchBox,
    SpinButton,
    Slider,
    ProgressBar,
    ScrollBar,
    Separator,
    ToolBar,
    List,
    ListItem,
    TreeGrid,
    Row,
    Tab,
    TabList,
    TabPanel,
    Menu,
    MenuBar,
    MenuItem,
    ComboBox,
    Document,
    Image,
    Dialog,
    Window,
};

enum class ICoreUIKitAccessibleTristate { False, True, Mixed, Undefined };

ICoreUIKitAppliedGround.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitAppliedGround.h

ICoreUIKitAppliedGround#

ICoreUIKitAppliedGround.h:10 · struct · 0 declaration(s)

The ground a style rule applies to a view (tablet port, TB2.16): ICoreAppKitView::AppliedGround's fields, for the uikit binding's icoreApplyStyleSpec (Theme/UIKitBinding/ICoreStyleApply.cpp).

struct ICoreUIKitAppliedGround {
public:
    bool   hasFill      = false;
    double fillR = 0.0, fillG = 0.0, fillB = 0.0, fillA = 0.0;
    bool   hasBorder    = false;
    double borderR = 0.0, borderG = 0.0, borderB = 0.0, borderA = 0.0;
    double borderWidth  = -1.0;
    double cornerRadius = -1.0;
};
};

ICoreUIKitButtonPainter.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitButtonPainter.h

Tablet port, TB2.9: the UIKit twin of Backends/Web/Widgets/ ICoreWebButtonPainter.h, renamed. It names no toolkit; a change to the shared painting belongs in both (and in GTK4's, which both descend from).

The web backend's copy of UI/Backends/Gtk4/Widgets/ICoreGtk4ButtonPainter.h, which names no toolkit; its reasoning is in that file.

Declares no class of its own — see the file.

ICoreUIKitItemDelegateAccess.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitItemDelegateAccess.h

Tablet port, TB2.23: the UIKit twin of Backends/Web/Widgets/ICoreWebItemDelegateAccess.h, renamed. It names no toolkit; a change to the shared behaviour belongs in both.

Web backend, WB2.4 -- the delegate's Impl, shared by the tree, ported from UI/Backends/Gtk4/Widgets/ICoreGtk4ItemDelegateAccess.h onto ICoreWebNode. The reasons for the behaviour are in that file's comments and are not repeated here; a behaviour change in one belongs in both.

ICoreItemDelegateHooks#

ICoreUIKitItemDelegateAccess.h:14 · class · 4 declaration(s)

class ICoreItemDelegateHooks {
public:
    virtual ~ICoreItemDelegateHooks() = default;

    virtual bool paint(ICorePainter& painter, const ICoreItemRenderContext& context) = 0;
    virtual ICoreSizeF sizeHint(const ICoreItemRenderContext& context) = 0;
    virtual ICoreColor selectedTextColorFor(const ICoreItemRenderContext& context) = 0;
};
};

ICoreItemDelegate#

ICoreUIKitItemDelegateAccess.h:24 · class · bases :Impl : public ICoreItemDelegateHooks · 4 declaration(s)

class ICoreItemDelegate : :Impl : public ICoreItemDelegateHooks {
public:
    explicit Impl(ICoreItemDelegate& owner);

    bool paint(ICorePainter& painter, const ICoreItemRenderContext& context) override;
    ICoreSizeF sizeHint(const ICoreItemRenderContext& context) override;
    ICoreColor selectedTextColorFor(const ICoreItemRenderContext& context) override;

    ICoreItemDelegate* m_owner;
};
};

ICoreUIKitItemViewPainter.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitItemViewPainter.h

Tablet port, TB2.9: the UIKit twin of Backends/Web/Widgets/ ICoreWebItemViewPainter.h, renamed. It names no toolkit; a change to the shared painting belongs in both.

Web backend, WB2.4 -- the item-view ink and row painter, ported from UI/Backends/Gtk4/Widgets/ICoreGtk4ItemViewPainter.h onto ICoreUIKitNode. The reasons for the behaviour are in that file's comments and are not repeated here; a behaviour change in one belongs in both.

ICoreUIKitItemRowInk#

ICoreUIKitItemViewPainter.h:19 · struct · 0 declaration(s)

struct ICoreUIKitItemRowInk {
public:
    ICoreRgba wash;

    ICoreRgba ink;

    bool spansRow = false;

    ICoreRgba leftEdge;
    double leftEdgeWidth = 0.0;

    ICoreRgba hairline;
    double hairlineWidth = 0.0;

    double radius = -1.0;

    double paddingLeft = 0.0;
};
};

ICoreUIKitItemHeaderInk#

ICoreUIKitItemViewPainter.h:42 · struct · 0 declaration(s)

struct ICoreUIKitItemHeaderInk {
public:
    ICoreRgba background;
    ICoreRgba ink;
    ICoreRgba underline;          // borderBottom -- "no frame, one hairline"
    double underlineWidth = 0.0;
    double paddingLeft = 0.0;
};
};

ICoreUIKitScrollBarPainter.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitScrollBarPainter.h

Tablet port, TB2.9: the UIKit twin of Backends/Web/Widgets/ ICoreWebScrollBarPainter.h, renamed. It names no toolkit; a change to the shared painting belongs in both.

The web backend's copy of UI/Backends/Gtk4/Widgets/ICoreGtk4ScrollBarPainter.h (web backend, WB2.5).

⚠ THIS FILE NAMES NO TOOLKIT, AND IT IS THE GTK4 PAINTER WITH THE BACKEND NAME CHANGED: it draws through ICorePainter from the theme's ICoreStyleSpec. The reasoning behind every line is in that file's comments and is not repeated here (one fact, one place). A change to the shared behaviour belongs in BOTH copies.

ICoreUIKitScrollBarInk#

ICoreUIKitScrollBarPainter.h:23 · struct · 0 declaration(s)

struct ICoreUIKitScrollBarInk {
public:
    ICoreRgba track;

    ICoreRgba thumb;
    ICoreRgba thumbBorder;
    double thumbBorderWidth = -1.0;     // < 0 is unset, per ICoreStyleEdge

    double radius = -1.0;
};
};

File-scope declarations#

enum class ICoreUIKitScrollThumbState { Idle, Hover, Pressed };

ICoreUIKitSpinBoxPainter.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitSpinBoxPainter.h

Tablet port, TB2.23: the UIKit twin of the web spin-box painter, renamed.

The web backend's copy of UI/Backends/Gtk4/Widgets/ICoreGtk4SpinBoxPainter.h, which names no toolkit; its reasoning is in that file (web backend, WB2.2).

Declares no class of its own — see the file.

ICoreUIKitSplitterPainter.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitSplitterPainter.h

The UIKit backend's splitter divider painter: the web backend's, which is the gtk4 backend's, with the backend renamed -- the third identical copy, and a candidate for UI/Portable/.

ICoreUIKitSplitterHandleInk#

ICoreUIKitSplitterPainter.h:17 · struct · 0 declaration(s)

struct ICoreUIKitSplitterHandleInk {
public:
    ICoreRgba background;
    ICoreRgba border;
    double borderWidth = -1.0;      // < 0 is unset, per ICoreStyleEdge
};
};

File-scope declarations#

enum class ICoreUIKitSplitterHandleState { Idle, Hover, Pressed };

ICoreUIKitStandardItemAccess.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitStandardItemAccess.h

Tablet port, TB2.23: the UIKit twin of Backends/Web/Widgets/ICoreWebStandardItemAccess.h, renamed. It names no toolkit; a change to the shared behaviour belongs in both.

Web backend, WB2.4 -- the standard item's Impl, shared by the model and the view, ported from UI/Backends/Gtk4/Widgets/ICoreGtk4StandardItemAccess.h onto ICoreWebNode. The reasons for the behaviour are in that file's comments and are not repeated here; a behaviour change in one belongs in both.

ICoreStandardItem#

ICoreUIKitStandardItemAccess.h:20 · class · bases :Impl · 10 declaration(s)

class ICoreStandardItem : :Impl {
public:
    explicit Impl(ICoreStandardItem& owner);
    Impl(ICoreStandardItem& owner, const ICoreString& text);
    ~Impl();

    Impl(const Impl&) = delete;
    Impl& operator=(const Impl&) = delete;

    void detachOwner();
    ICoreStandardItem* owner() const;

    void setRoleText(int role, const ICoreString& value);
    void setRoleInt(int role, int value);

    ICoreString roleAsText(int role) const;

    ICoreString label;
    ICoreIcon icon;
    bool hasIcon = false;
    bool editable = true;

    std::map<int, ICoreString> textRoles;
    std::map<int, int> intRoles;

    std::vector<std::shared_ptr<Impl>> children;
    std::vector<std::shared_ptr<Impl>> cells;
    Impl* parentNode = nullptr;

    std::weak_ptr<Impl> selfWeak;

    ICoreStandardItem* m_owner = nullptr;
};
};

ICoreUIKitTextField.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitTextField.h

Declares no class of its own — see the file.

ICoreUIKitTextView.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitTextView.h

Declares no class of its own — see the file.

ICoreUIKitTreeModelAccess.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitTreeModelAccess.h

Tablet port, TB2.23: the UIKit twin of Backends/Web/Widgets/ICoreWebTreeModelAccess.h, renamed. It names no toolkit; a change to the shared behaviour belongs in both.

Web backend, WB2.4 -- the model's Impl, shared by the view, ported from UI/Backends/Gtk4/Widgets/ICoreGtk4TreeModelAccess.h onto ICoreWebNode. The reasons for the behaviour are in that file's comments and are not repeated here; a behaviour change in one belongs in both.

ICoreTreeViewModel#

ICoreUIKitTreeModelAccess.h:19 · class · bases :State · 0 declaration(s)

class ICoreTreeViewModel : :State {
public:
    bool alive = true;
};
};

ICoreTreeViewModel#

ICoreUIKitTreeModelAccess.h:24 · class · bases :Impl · 4 declaration(s)

class ICoreTreeViewModel : :Impl {
public:
    explicit Impl(ICoreTreeViewModel& owner);

    Impl(const Impl&) = delete;
    Impl& operator=(const Impl&) = delete;

    void detachOwner();

    std::vector<std::shared_ptr<ICoreStandardItem::Impl>> rows;
    std::vector<ICoreString> headers;
    ICoreNativeWidget* parent = nullptr;
    ICoreTreeViewModel* m_owner = nullptr;
};
};

ICoreUIKitView.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitView.h

ICoreUIKitView -- one UIView and the C++ state behind it: the seat every ICoreWidget on iPadOS stands on.

The same idea as the AppKit backend's ICoreAppKitView, and deliberately the same shape: ICoreWidget's UIKit file is written against this class and never names a UIKit type in its own logic, and the backend files that come later (layouts, event translation, the window) reach a widget's view through icoreUIKitView() below rather than through the wrapper.

A header in this zone names no Objective-C type, so the UIView travels as void* (nativeView()). Nothing outside UI/Backends/UIKit/ includes this.

The view is y-down with its origin at the top-left, which is UIKit's own orientation and the one every ICoreWidget hook already assumes. A paint hook

ICoreUIKitPointerInput#

ICoreUIKitView.h:39 · struct · 0 declaration(s)

One pointer event as a hook sees it, in the view's own coordinates.

struct ICoreUIKitPointerInput {
public:
    double x = 0.0;
    double y = 0.0;
    ICoreMouseButton button = ICoreMouseButton::None;
    ICoreMouseButtons buttons = 0;
    ICoreKeyModifiers modifiers = 0;
    int clickCount = 1;
    double scrollX = 0.0;
    double scrollY = 0.0;
    ICorePointerKind kind = ICorePointerKind::Mouse;
    double pressure = 1.0;
};
};

ICoreUIKitKeyInput#

ICoreUIKitView.h:53 · struct · 0 declaration(s)

One key, from a hardware keyboard (UIKey) or the soft one.

struct ICoreUIKitKeyInput {
public:
    ICoreKey key = static_cast<ICoreKey>(0);
    bool recognised = false;
    std::string text;
    ICoreKeyModifiers modifiers = 0;
    bool isRepeat = false;
};
};

ICoreUIKitSizeConstraints#

ICoreUIKitView.h:63 · struct · 0 declaration(s)

What a wrapper publishes for the layout tier to read: the same fields, the same 0-is-unbounded convention, as ICoreAppKitSizeConstraints.

struct ICoreUIKitSizeConstraints {
public:
    int minimumWidth = 0;
    int minimumHeight = 0;
    int preferredWidth = 0;
    int preferredHeight = 0;
    int maximumWidth = 0;
    int maximumHeight = 0;
    bool fixedWidth = false;
    bool fixedHeight = false;
    int horizontalStretch = 0;
    int verticalStretch = 0;
};
};

ICoreUIKitView#

ICoreUIKitView.h:76 · class · pImpl · 89 declaration(s)

class ICoreUIKitView {
public:
    ICoreUIKitView();
    ~ICoreUIKitView();
    ICoreUIKitView(const ICoreUIKitView&) = delete;
    ICoreUIKitView& operator=(const ICoreUIKitView&) = delete;

    // The UIView, as a borrowed UIView*. Never null while this object lives.
    [[nodiscard]] void* nativeView() const;

    // The seat a UIView belongs to, or null for a view no seat made (a
    // window's own root, a system view).
    [[nodiscard]] static ICoreUIKitView* fromNativeView(void* uiView);

    // A serial issued at construction; with the address it names THIS seat,
    // where the address alone may name a later one allocated in its place.
    // isLive() is false once the seat is destroyed. For code that holds a seat
    // across events (the touch router's grab).
    [[nodiscard]] unsigned long long serial() const;
    [[nodiscard]] static bool isLive(const ICoreUIKitView* view, unsigned long long serial);
    // Whether `handle` is a live seat at all, for code handed an opaque native
    // handle that may name something else (the motion tier's animation targets, TB2.22).
    [[nodiscard]] static bool isLiveSeat(const void* handle);

    // -- geometry, in the parent's coordinates --------------------------------
    void setFrame(double x, double y, double width, double height);
    void frame(double& x, double& y, double& width, double& height) const;
    // The size of the view's own coordinate space (its bounds).
    void contentSize(double& width, double& height) const;

    // Margins a layout keeps clear inside this view (ICoreWidget::setContentsMargins).
    void setContentsMargins(int left, int top, int right, int bottom);
    void contentsMargins(int& left, int& top, int& right, int& bottom) const;

    // The size a fresh widget starts at: 100 x 30 with a parent and 640 x 480
    // without, as on every other seat. Called once, before any hook exists, so
    // it reports no resize.
    void applyConstructionDefaultSize(bool hasParent);

    // Fired when the SIZE changes, from any path: setFrame() and UIKit's own
    // layout alike, de-duplicated against the last size reported and guarded
    // against re-entry. setFrameChangedHook() replaces the one primary hook;
    // addFrameChangedHook() appends an observer that fires after it.
    using FrameChangedHook = std::function<void(double width, double height)>;
    void setFrameChangedHook(FrameChangedHook hook);
    void addFrameChangedHook(FrameChangedHook hook);

    // Fired when what the view WANTS to be has changed (its constraints), for
    // the layout tier to re-measure. Not de-duplicated: it carries no size.
    using GeometryInvalidatedHook = std::function<void()>;
    void setGeometryInvalidatedHook(GeometryInvalidatedHook hook);
    void notifyGeometryInvalidated();

    using HeightForWidthHook = std::function<int(int width)>;
    void setHeightForWidthHook(HeightForWidthHook hook);
    [[nodiscard]] bool hasHeightForWidth() const;
    [[nodiscard]] int heightForWidth(int width) const;

    // -- hierarchy ------------------------------------------------------------
    // Appends `child` as the topmost subview. A child already elsewhere moves.
    void addChild(ICoreUIKitView& child);
    void removeFromParent();
    // Puts this view above its siblings.
    void raise();
    // The nearest seat up the UIKit superview chain -- not only the one that
    // called addChild(), so a view inside a scroll view still finds its seat.
    [[nodiscard]] ICoreUIKitView* parentView() const;
    // The outermost seat above this one (this, if none).
    [[nodiscard]] ICoreUIKitView* topLevelSeat() const;
    // This view's origin in `ancestor`'s coordinates.
    void originIn(const ICoreUIKitView& ancestor, double& outX, double& outY) const;
    [[nodiscard]] int childCount() const;

    // -- visibility and look --------------------------------------------------
    void setVisible(bool visible);
    [[nodiscard]] bool isVisible() const;
    void setOpacity(double opacity);
    [[nodiscard]] double opacity() const;
    void setShadow(double red, double green, double blue, double alpha,
                   double blurRadius, double offsetX, double offsetY);
    void clearShadow();
    [[nodiscard]] bool hasShadow() const;
    // Off by default, as on AppKit: a child may draw outside its parent.
    void setClipsChildren(bool clips);
    [[nodiscard]] bool clipsChildren() const;

    // Ties `object`'s lifetime to this view's. Released first in ~ICoreUIKitView.
    void adoptOwnedObject(std::shared_ptr<void> object);

    // -- constraints the layout tier reads ------------------------------------
    void setSizeConstraints(const ICoreUIKitSizeConstraints& constraints);
    // The AppKit seat's pins: minimum, preferred and maximum all set, so no
    // layout can stretch or shrink that axis (TB2.8, for the line edit).
    void setFixedHeight(int height);
    void setFixedWidth(int width);
    [[nodiscard]] const ICoreUIKitSizeConstraints& sizeConstraints() const;

    // -- painting ---------------------------------------------------------------
    // Ask for the whole view, or part of it, to be painted again. Coalesced by
    // UIKit into the next display pass.
    void update();
    void updateRect(double x, double y, double width, double height);

    // The scope a subscription tied to this view's lifetime connects through.
    [[nodiscard]] const ICoreSignalScope& subscriptionScope() const;

    // Paints this view's content; `dirty` is in its own coordinates.
    using PaintHook = std::function<void(ICoreAppKitPainter&, const ICoreAppKitRect&)>;
    void setPaintHook(PaintHook hook);

    // Composites this view and its visible subtree into a y-up CoreGraphics
    // context of height `surfaceHeight` -- a bitmap, an ICorePixmap's context.
    // The same paint hooks a real display pass runs, so the two cannot differ.
    void renderInto(void* cgContext, double surfaceHeight);

    // -- input: hooks the event translation delivers into ----------------------
    // The view's own UIKit overrides (touches, presses, hover, scroll) feed
    // the touch router (UIKit/Events/ICoreUIKitTouchRouter.h), which calls
    // these. A probe may call them directly.
    using PointerPressHook = std::function<bool(const ICoreUIKitPointerInput&)>;
    using PointerHook = std::function<void(const ICoreUIKitPointerInput&)>;
    void setPointerPressHook(PointerPressHook hook);
    void setPointerReleaseHook(PointerHook hook);
    void setPointerMoveHook(PointerHook hook);
    // A press this view answered that will never be released (the system took
    // the touch). ICoreWidget::mouseGestureCancelled().
    void setPointerCancelHook(std::function<void()> hook);
    using WheelHook = std::function<bool(const ICoreUIKitPointerInput&)>;
    void setWheelHook(WheelHook hook);
    void setHoverHook(std::function<void(bool inside)> hook);
    using KeyHook = std::function<bool(const ICoreUIKitKeyInput&)>;
    void setKeyPressHook(KeyHook hook);
    void setKeyReleaseHook(KeyHook hook);
    // A context menu asked for at a SCREEN point: a finger's long press or a
    // trackpad's secondary click. True when the widget showed one, which ends
    // the walk up the parents. ICoreWidget::contextMenuRequested().
    using ContextMenuHook = std::function<bool(double screenX, double screenY)>;
    void setContextMenuHook(ContextMenuHook hook);

    // What the hooks answered, for the translation to decide whether an event
    // walks on to the parent. Each returns false when no hook is installed.
    bool deliverPointerPress(const ICoreUIKitPointerInput& input);
    void deliverPointerRelease(const ICoreUIKitPointerInput& input);
    void deliverPointerMove(const ICoreUIKitPointerInput& input);
    void deliverPointerCancel();
    bool deliverWheel(const ICoreUIKitPointerInput& input);
    void deliverHover(bool inside);
    bool deliverKey(const ICoreUIKitKeyInput& input);
    bool deliverKeyRelease(const ICoreUIKitKeyInput& input);
    bool deliverContextMenu(double screenX, double screenY);

    // Removes this view from hit testing: a touch lands on whatever is under
    // it, its parent included (Qt's WA_TransparentForMouseEvents). Its children
    // stay hittable.
    void setPointerTransparent(bool transparent);
    [[nodiscard]] bool isPointerTransparent() const;
    void setMouseTracking(bool tracking);
    [[nodiscard]] bool hasMouseTracking() const;
    [[nodiscard]] bool isUnderPointer() const;

    // The shape a pointer interaction shows over this view.
    void setCursor(ICoreCursorShape cursor);
    [[nodiscard]] ICoreCursorShape cursor() const;

    // Adds this view's UIDragInteraction when an ICoreDragSource with a
    // provider is installed on it, and removes it when none is. Called by the
    // source's install observer; idempotent.
    void syncDragSource();
    [[nodiscard]] bool hasDragInteraction() const;

    // Held for the long-press affordance (UI/Portable/ICoreTouchHover.h) to
    // show: iPadOS has no hover tooltip of its own.
    void setToolTip(const std::string& utf8);
    [[nodiscard]] std::string toolTip() const;

    // -- focus: the first responder -------------------------------------------
    void setFocusable(bool focusable);
    [[nodiscard]] bool isFocusable() const;
    void setClaimsKeyboard(bool claims);
    [[nodiscard]] bool claimsKeyboard() const;
    // Makes the view first responder. False when it is not focusable or has
    // no window yet.
    bool takeFocus(ICoreFocusReason reason);
    [[nodiscard]] bool hasFocus() const;
    void setFocusChangedHook(std::function<void(bool focused, ICoreFocusReason reason)> hook);

    // -- coordinates ------------------------------------------------------------
    // True once the view is in a window, which is when "screen" means something.
    [[nodiscard]] bool hasScreenMapping() const;
    // In the screen's coordinate space (UIScreen.coordinateSpace), in points.
    void mapToScreen(double x, double y, double& screenX, double& screenY) const;
    void mapFromScreen(double screenX, double screenY, double& x, double& y) const;
    // The points-to-pixels ratio of the screen the view is on (the main
    // screen's before it has one).
    [[nodiscard]] double devicePixelRatio() const;

    // -- test seams ---------------------------------------------------------------
    [[nodiscard]] int updateRequestCountForTest() const;
    void resetUpdateRequestCountForTest();

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreUIKitAccessibilityQuery#

ICoreUIKitView.h:320 · struct · 8 declaration(s)

Accessibility.

struct ICoreUIKitAccessibilityQuery {
public:
    bool (*has)(const ICoreUIKitView* view);
    bool (*isElement)(const ICoreUIKitView* view);
    std::string (*label)(const ICoreUIKitView* view);
    std::string (*hint)(const ICoreUIKitView* view);
    std::string (*value)(const ICoreUIKitView* view);
    unsigned long long (*traits)(const ICoreUIKitView* view);
    bool (*hidden)(const ICoreUIKitView* view);
    bool (*activate)(ICoreUIKitView* view);
};
};

File-scope declarations#

// Shortcuts. ICoreShortcut's registry (UIKit/Windows/ICoreShortcut.mm) installs
// its dispatcher here when the first shortcut is made, so a key press can be
// offered to it by code that does not link the registry. The focused seat's
// view offers every press BEFORE its widget sees it (Qt's order, and the web
// seat's); a window's root view controller may offer one with no focus.
// `uiViewInWindow` is any view in the key's window, for the Window scope.
using ICoreUIKitShortcutDispatcher = bool (*)(ICoreUIKitView* focus, void* uiViewInWindow,
                                              const ICoreUIKitKeyInput& input);

ICoreUIKitWebShape.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitWebShape.h

The web node's hook shapes, over ICoreUIKitView (tablet port, TB2.23).

Most uikit control seats are ported from the web backend's, which are themselves GTK4's (the web's Widgets/ICoreWebNode.h presents ICoreGtk4Widget's surface). A web seat talks to its node through a handful of hook shapes: paint(painter, width, height), resized(width, height), and pointer, key and scroll records with the web's field names. This header gives the UIKit seat those same shapes as free functions over the view's public API, so a ported seat's BODIES stay line-for-line the web's, and a fix made to one copy can be carried to the other by reading, not re-deriving. The label, button and list box (TB2.9) were ported before this header existed and speak ICoreUIKitView directly; both spellings drive the same seat.

ICoreUIKitWebPointer#

ICoreUIKitWebShape.h:32 · struct · 0 declaration(s)

The web's ICoreWebPointerInput, filled from the seat's input.

struct ICoreUIKitWebPointer {
public:
    double x = 0.0;
    double y = 0.0;
    double rootX = 0.0;           // the seat's mapToScreen: the web's page space
    double rootY = 0.0;
    unsigned int button = 0;      // ICoreMouseButton bit of the button that changed; 0 for a move
    unsigned int buttons = 0;     // ICoreMouseButton bits held
    unsigned int modifiers = 0;   // ICoreKeyModifier bits
    int pressCount = 0;           // 2 is a double click
};
};

ICoreUIKitWebKey#

ICoreUIKitWebShape.h:44 · struct · 0 declaration(s)

The web's ICoreWebKeyInput.

struct ICoreUIKitWebKey {
public:
    int key = 0;
    unsigned int modifiers = 0;
    std::string text;
};
};

ICoreUIKitWebScroll#

ICoreUIKitWebShape.h:51 · struct · 0 declaration(s)

The web's ICoreWebScrollInput, in ICoreWheelEvent units.

struct ICoreUIKitWebScroll {
public:
    double x = 0.0;
    double y = 0.0;
    double deltaX = 0.0;
    double deltaY = 0.0;
    unsigned int modifiers = 0;
};
};

ICoreUIKitWidgetAccess.h#

ICoreEssentials/UI/Backends/UIKit/Widgets/ICoreUIKitWidgetAccess.h

What the rest of the UIKit backend needs from ICoreWidget's seat and cannot reach through the wrapper's public surface. Nothing outside UI/Backends/UIKit/ includes this. The AppKit backend's equivalents are ICoreAppKitWidgetLiveness.h, ICoreAppKitWatchRegistry.h and ICoreAppKitPointerMonitor.h, and each rule below is theirs.

File-scope declarations#

// -- the application-wide pointer monitor --------------------------------------
// ICoreWidget::watchOutsidePointerPresses and watchApplicationPointerMoves
// subscribe here. The event translation (Events/ICoreUIKitTouchRouter) reports every press and every
// move, in screen coordinates (UIScreen.coordinateSpace), BEFORE it delivers
// the event to a view. Tokens are never 0; removing 0 or an unknown token is a
// no-op, and an observer may remove itself from inside the call.
using ICoreUIKitPointerObserver = std::function<void(double screenX, double screenY)>;

ICoreUIKitPromptsAccess.h#

ICoreEssentials/UI/Backends/UIKit/Windows/ICoreUIKitPromptsAccess.h

Test seams for the UIKit prompts and pickers (ICoreMessageBox, ICoreInputDialog, ICoreFileDialog, ICoreColorDialog, ICoreFontDialog).

A probe cannot tap a UIAlertAction or pick a file in the system picker, so each seat routes its answer through ONE completion path, and these drive that path: what a tap on a button, or a pick in a picker, would have called. What they cannot prove is the tap itself. Nothing outside UI/Backends/UIKit/ and its probes includes this.

Declares no class of its own — see the file.

ICoreUIKitTitleBarSeat.h#

ICoreEssentials/UI/Backends/UIKit/Windows/ICoreUIKitTitleBarSeat.h

ICoreUIKitTitleBarSeat#

ICoreUIKitTitleBarSeat.h:26 · class · bases public ICoreTitleBarHost · pImpl · 14 declaration(s)

The iPadOS seat for ICoreTitleBar -- the web seat's shape (Backends/Web/Windows/ICoreWebTitleBarSeat.h), over ICoreUIKitWindow's caption slot.

class ICoreUIKitTitleBarSeat : public ICoreTitleBarHost {
public:
    ICoreUIKitTitleBarSeat(std::function<ICoreUIKitWindow*()> windowOf, ICoreTitleBarRole role);
    ~ICoreUIKitTitleBarSeat() override;
    ICoreUIKitTitleBarSeat(const ICoreUIKitTitleBarSeat&) = delete;
    ICoreUIKitTitleBarSeat& operator=(const ICoreUIKitTitleBarSeat&) = delete;

    // The explicit choice, owned from here on; nullptr removes the strip.
    // Either opts out of ICoreTitleBarProvider.
    void setBar(ICoreTitleBar* bar);
    [[nodiscard]] ICoreTitleBar* bar() const;

    // Ask ICoreTitleBarProvider once, before the window's first show.
    void adoptDefaultIfNeeded();

    void titleBarBeginMove() override;
    void titleBarDoubleClicked() override;
    void titleBarMinimize() override;
    void titleBarToggleMaximize() override;
    void titleBarClose() override;
    [[nodiscard]] bool titleBarDragsItself() const override;
    void titleBarChanged() override;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreUIKitWindow.h#

ICoreEssentials/UI/Backends/UIKit/Windows/ICoreUIKitWindow.h

Backend-internal: the toolkit window behind one ICoreWindow on iPadOS. No Objective-C in this header -- views travel as void* and are UIView* on the far side.

⚠ AN iPadOS WINDOW IS A SCENE, AND THE SYSTEM OWNS ITS FRAME. One of these holds a UIWindow in one UIWindowScene. Several are several scenes, which the user arranges; an application can ask for a new scene but cannot place or size one (the frame API is Mac Catalyst's alone). So:

• show() takes a connected scene nobody holds, or asks UIKit for a new one

and attaches when it connects. Before the launch scene has connected it simply waits for it.

• setContentSize() and move() are REQUESTS the system is free to ignore.

contentSize() reports the real size once attached, and the resized hook

ICoreUIKitWindow#

ICoreUIKitWindow.h:49 · class · pImpl · 29 declaration(s)

class ICoreUIKitWindow {
public:
    ICoreUIKitWindow();
    ~ICoreUIKitWindow();

    ICoreUIKitWindow(const ICoreUIKitWindow&) = delete;
    ICoreUIKitWindow& operator=(const ICoreUIKitWindow&) = delete;

    // The UIView filling the content area, or nullptr. Not owned.
    void setContentView(void* uiView);
    [[nodiscard]] void* contentView() const;

    // The root view of this window's view controller: stable for this object's
    // whole life, across every scene it is attached to.
    [[nodiscard]] void* rootView() const;

    // -- the caption: an ICoreTitleBar's strip (ICoreUIKitTitleBarSeat.h) ------
    // A view `height` points tall across the top of the safe area. The content
    // view goes under it, and contentSize() and the resized hook report the
    // area below it. Null (or a height of 0) removes it. Not owned.
    void setCaptionView(void* uiView, int height);
    [[nodiscard]] void* captionView() const;
    [[nodiscard]] int captionHeight() const;
    // The strips at the caption's two ends that the system's window controls
    // and the display's corners take: the safe area with its corners adapted
    // for (UIViewLayoutRegion, iPadOS 26), less the plain safe area. Zero
    // before a scene, and on a system without the API.
    void captionInsets(int& left, int& right) const;
    // Something the caption shows may have moved: its insets, the window's
    // activation, or its title.
    void setCaptionStateHook(std::function<void()> hook);

    void setContentSize(int width, int height);
    void contentSize(int& width, int& height) const;
    void setMinimumContentSize(int width, int height);
    void minimumContentSize(int& width, int& height) const;

    void show();
    void hide();          // gives the scene back (unless it is the last); the window stays
    void present();       // show, and bring this scene to the front
    void close();         // asks the closing hook first

    [[nodiscard]] bool isVisible() const;     // shown and not hidden or closed
    [[nodiscard]] bool isAttached() const;    // has a scene right now
    [[nodiscard]] bool isMinimized() const;   // open, but its scene is not in the foreground
    [[nodiscard]] bool isActive() const;      // foreground-active, and its window is key

    void setTitle(const std::string& title);
    [[nodiscard]] std::string title() const;
    void setOpacity(double opacity);
    [[nodiscard]] double devicePixelRatio() const;

    // The session this window is bound to, or "" before the first attach.
    [[nodiscard]] std::string sessionIdentifier() const;

    void setClosingHook(std::function<bool()> hook);   // false vetoes
    void setActivatedHook(std::function<void()> hook);
    void setShownHook(std::function<void()> hook);
    void setResizedHook(std::function<void(int contentWidth, int contentHeight)> hook);

    // A key no widget consumed. The focused widget's view passes a press it
    // did not take up the responder chain, and this window's root view
    // controller is the last stop inside the window; it translates the press
    // with the event map and calls this. Also the probe's way in, because a
    // UIPress cannot be made outside UIKit. The Window- and Application-scope
    // shortcuts are offered the key first, then the hook. Answers whether
    // either took it; a key neither took goes on to UIKit.
    using KeyPressedHook = std::function<bool(ICoreKey key, ICoreKeyModifiers modifiers,
                                              const std::string& text)>;
    void setKeyPressedHook(KeyPressedHook hook);
    bool deliverKey(ICoreKey key, ICoreKeyModifiers modifiers, const std::string& text);

    [[nodiscard]] static std::vector<ICoreUIKitWindow*> windows();
    [[nodiscard]] static ICoreUIKitWindow* activeWindow();

    class Impl;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};