API — ICoreEssentials/UI/Backends/Gtk4/System

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

ICoreGtk4AppAccess.h#

ICoreEssentials/UI/Backends/Gtk4/System/ICoreGtk4AppAccess.h

What the rest of THIS ZONE may ask the application seat for (L1.1).

The peer of ../../WinUI/ICoreWinUIDispatcher.h + ICoreWinUIWake.h and of the AppKit backend's reach for NSApp: the callers are free functions and seats with no ICoreApplication in hand, so the process's one application object is published here rather than threaded through every constructor.

⚠ NOTHING ABOVE src/ICoreEssentials/UI/Backends/Gtk4/ MAY INCLUDE THIS. It names GTK in a header, which is exactly what the architecture census row R2.4 refuses everywhere else in this tree.

Every accessor answers safely before the application exists and after it has been destroyed -- null, or a no-op. A seat constructed by a unit rig that never built an ICoreApplication is a real case, not a defensive one.

Declares no class of its own — see the file.

ICoreGtk4AppearanceAccess.h#

ICoreEssentials/UI/Backends/Gtk4/System/ICoreGtk4AppearanceAccess.h

Backend-internal access to the "what does the OS look like" decision (L6.2).

⚠ NOTHING ABOVE THE BACKEND ZONE MAY INCLUDE THIS.

⚠⚠ THE DECISION IS SEPARATED FROM THE TOOLKIT BECAUSE THE DECISION IS THE PART THAT CAN BE WRONG.

ICoreSystemAppearance::isDarkMode() reads two sources on this platform, and which one wins, what a missing answer means and what "no preference" falls back to are all judgements. Reaching them through a live D-Bus session bus and a live desktop theme means a suite can only ever assert whatever this machine happens to be set to today -- which is one of the three portal answers and one shape of theme name.

ICoreGtk4ColorScheme#

ICoreGtk4AppearanceAccess.h:35 · struct · 0 declaration(s)

What the XDG settings portal said, if anything.

struct ICoreGtk4ColorScheme {
public:
    bool answered = false;

    // The portal's own numbering (org.freedesktop.appearance):
    //   0  no preference   1  prefer dark   2  prefer light
    //
    // ⚠ 0 IS NOT LIGHT. It means the desktop declines to say, which is a
    // different answer from saying light -- and it is the one that has to fall
    // through to the theme name rather than resolve.
    unsigned value = 0;
};
};

ICoreGtk4DragPayload.h#

ICoreEssentials/UI/Backends/Gtk4/System/ICoreGtk4DragPayload.h

ICoreGtk4DragFormat#

ICoreGtk4DragPayload.h:24 · struct · 0 declaration(s)

One advertised format and the bytes offered under it.

struct ICoreGtk4DragFormat {
public:
    std::string mimeType;
    std::string data;
};
};

ICoreGtk4DragPlan#

ICoreGtk4DragPayload.h:36 · struct · 3 declaration(s)

The whole advertisement, in the order it is offered.

struct ICoreGtk4DragPlan {
public:
    std::vector<ICoreGtk4DragFormat> formats;

    [[nodiscard]] bool isEmpty() const;

    // The bytes advertised under `mimeType`, or an empty string. For the suite
    // and for the provider builder; `has()` distinguishes absent from empty.
    [[nodiscard]] bool has(const std::string& mimeType) const;
    [[nodiscard]] std::string dataFor(const std::string& mimeType) const;
};
};

ICoreGtk4ResourceBytes.h#

ICoreEssentials/UI/Backends/Gtk4/System/ICoreGtk4ResourceBytes.h

The zone's one answer to "a path in this tree could be a resource or a file".

⚠ THIS IS NOT A RESOLVER, AND THE DIFFERENCE MATTERS ENOUGH TO SAY. Backends/AppKit/System/ICoreAppKitResources.h turns ":/SVGs/x.svg" into a real path inside an .app bundle, because on that backend the bytes are a FILE. Here they are not: ICoreEmbeddedResources has been a byte array compiled into the binary since W9.5, so there is no path to resolve TO and a Gtk4Resources peer would be a second answer to a question that already has one (§L29.6). What this header holds is the READ, which is the only half this backend needs.

⚠ NOTHING ABOVE THE BACKEND ZONE MAY INCLUDE THIS.

⚠ IT EXISTS BECAUSE THE SAME EIGHT LINES WERE ABOUT TO BE WRITTEN A THIRD

Declares no class of its own — see the file.

ICoreGtk4WeakRef.h#

ICoreEssentials/UI/Backends/Gtk4/System/ICoreGtk4WeakRef.h

The one weak-reference mechanism this backend uses, wrapped once so the three weak-handle seats beside it do not each write the same six lines.

⚠ NOTHING ABOVE src/ICoreEssentials/UI/Backends/Gtk4/ MAY INCLUDE THIS.

⚠⚠ GWeakRef, AND NOT g_object_add_weak_pointer, WHICH IS WHAT THE ROW'S OWN TITLE NAMES. The difference is the reason this header exists.

g_object_add_weak_pointer(object, &myPointer) registers THE ADDRESS OF A VARIABLE. The three classes seated on top of this are COPYABLE and MOVABLE value types stored in an inline byte buffer -- copy one into a std::vector that then reallocates, and GObject is still holding the address of the old storage and will write a NULL through it when the object dies. That is a heap write into freed memory, at an unrelated moment, with nothing in the

ICoreGtk4WeakRef#

ICoreGtk4WeakRef.h:49 · class · 11 declaration(s)

A GWeakRef living in a caller's storage.

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

    ICoreGtk4WeakRef(const ICoreGtk4WeakRef& other);
    ICoreGtk4WeakRef& operator=(const ICoreGtk4WeakRef& other);
    ICoreGtk4WeakRef(ICoreGtk4WeakRef&& other) noexcept;
    ICoreGtk4WeakRef& operator=(ICoreGtk4WeakRef&& other) noexcept;

    // Binds to `object`. Null unbinds.
    //
    // ⚠⚠ THE `G_IS_OBJECT` GUARD INSIDE CATCHES LESS THAN IT LOOKS LIKE, AND
    // THE DIFFERENCE IS WORTH KNOWING BEFORE RELYING ON IT. `G_IS_OBJECT`
    // DEREFERENCES its argument -- it reads the instance's class pointer and
    // walks the type -- so it can tell a valid `GTypeInstance` that is not a
    // GObject from one that is, and it CANNOT tell either from a pointer that
    // was never a GObject at all. Handing it an arbitrary address segfaults, as
    // this rig's first version did.
    //
    // So the contract is the handle's, not this function's: an
    // `ICoreNativeHandle` from a widget wrapper on this backend IS a GObject,
    // and the guard is a type check rather than a validity check. The AppKit
    // seat's `(__bridge id)` is in exactly the same position one toolkit over.
    void bind(void* object);

    // The object, or null if it has died or was never bound. Borrowed.
    [[nodiscard]] void* get() const;

    [[nodiscard]] bool isNull() const;
    void clear();

    // ⚠ NOT `GWeakRef m_ref;` DIRECTLY, and the indirection is the header
    // surface rule rather than taste: this header would otherwise carry a
    // toolkit-typed data member, which is what R4.2's census refuses -- §L17.8
    // is the row that learned "backend-internal is not one of the four
    // exemptions". The buffer is checked against `sizeof(GWeakRef)` by a
    // static_assert in the .cpp.
    //
    // ⚠ AND THE TWO CONSTANTS ARE PUBLIC, WHICH IS NOT COSMETIC: the census
    // reads a private `static constexpr` as private DATA and fails the header,
    // which it did on the first version of this file. The three inline-storage
    // value types this one serves -- ICoreWeakObject, ICoreWeakWidget,
    // ICoreWeakNativeWidget -- all publish their `kNativeStorageSize` for the
    // same reason, and their seats static_assert against it.
    static constexpr std::size_t kStorageSize = sizeof(void*);
    static constexpr std::size_t kStorageAlign = alignof(void*);

};