API — ICoreEssentials/UI/System

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

ICoreActiveWindow.h#

src/ICoreEssentials/UI/System/ICoreActiveWindow.h

ICoreActiveWindow#

ICoreActiveWindow.h:8 · class · 2 declaration(s)

Which of this application's top-level windows currently has focus, as a static facade.

class ICoreActiveWindow {
public:
    ICoreActiveWindow() = delete;

    static QWidget* current();
};
};

ICoreApplication.h#

src/ICoreEssentials/UI/System/ICoreApplication.h

ICoreApplication#

ICoreApplication.h:48 · class · pImpl · 18 declaration(s)

ICoreApplication -- the process's toolkit application object, wrapped.

class ICoreApplication {
public:
    // Builds the toolkit application. argc/argv come straight from main(); the
    // STRINGS must outlive this object (their storage stays the caller's),
    // while the ARRAY need not -- an internal copy of the pointers is what the
    // toolkit is handed, because it shortens and shuffles that array in place
    // as it consumes the platform switches it recognises.
    //
    // Tolerates argc == 0 or a null argv by standing in a placeholder argv[0],
    // which is what a host embedding this in a process it did not start has.
    ICoreApplication(int argc, char** argv);
    ~ICoreApplication();

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

    // Lends the toolkit one slice. waitMs > 0 sleeps until something happens or
    // that long passes, whichever comes first -- which is what keeps an idle
    // application at 0% CPU instead of spinning the caller's loop. waitMs == 0
    // drains what is pending and returns.
    void tick(int waitMs = 0);

    // Ends the session at the caller's next look at isRunning(). FIRST CODE
    // WINS: a shutdown already under way is not relabelled, so a later
    // "everything closed, exit 0" cannot overwrite an earlier failure code.
    void requestQuit(int exitCode);

    [[nodiscard]] bool isRunning() const noexcept;
    [[nodiscard]] int exitCode() const noexcept;

    // The argument vector as the application proper sees it -- AFTER the
    // toolkit has taken out the platform switches it handles itself. That is
    // what makes it different from the argv handed to the constructor, and it
    // is the one an owner reading its own switches wants.
    [[nodiscard]] ICoreStringList arguments() const;

    // ----------------------------------------------------------------------
    // What the running application calls itself, and what it looks like before
    // any window exists. Set these BEFORE the first widget is built: several
    // are read once, when the platform integration comes up.
    // ----------------------------------------------------------------------

    // The name the window system knows this process by. It feeds the
    // Wayland/X11 app-id that desktop shells match against a .desktop file's
    // StartupWMClass, which is what lets a running window group under the
    // installed launcher icon instead of a generic placeholder.
    void setApplicationName(const ICoreString& name);

    // The human-readable name, which is what window titles fall back to.
    void setApplicationDisplayName(const ICoreString& name);
    void setApplicationVersion(const ICoreString& version);

    // The .desktop file's base name, sans extension -- the other half of the
    // app-id match above, and ignored on platforms that have no such file.
    void setDesktopFileName(const ICoreString& name);

    // The mark on every window: title bars, the taskbar, Alt-Tab, and the
    // Wayland/X11 fallback when no .desktop file is installed.
    //
    // ⚠ macOS IGNORES THIS and reads the bundle's .icns instead, so a Dock
    // icon that looks wrong is a packaging question, not a call-site one.
    void setWindowIcon(const ICoreIcon& icon);

    // Copy, modify, hand back -- see ICorePalette. The getter returns the
    // application's CURRENT palette, so a caller changing one role keeps
    // whatever the platform style chose for the rest.
    [[nodiscard]] ICorePalette palette() const;
    void setPalette(const ICorePalette& palette);

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

ICoreClipboard.h#

src/ICoreEssentials/UI/System/ICoreClipboard.h

ICoreClipboard#

ICoreClipboard.h:7 · class · 3 declaration(s)

The system clipboard, as a static facade (same shape as ICoreNativeDialogs: no instances, because there is only one clipboard and the OS owns it).

class ICoreClipboard {
public:
    ICoreClipboard() = delete;

    static void setText(const ICoreString& text);
    static ICoreString text();
};
};

ICoreDrag.h#

src/ICoreEssentials/UI/System/ICoreDrag.h

ICoreDrag#

ICoreDrag.h:13 · class · 2 declaration(s)

Starting a drag, as a static facade: the library-navigator entries begin a drag carrying a block/template payload and a preview pixmap.

class ICoreDrag {
public:
    ICoreDrag() = delete;

    // `source` is the widget the drag starts from -- the toolkit uses it to
    // decide which window owns the drag loop. Q1.8 swapped it from a raw
    // QWidget*: all three call sites were passing icoreNativeWidget(this), so
    // the wrapper was what they had in hand and the unwrap was pure ceremony.
    static bool exec(ICoreNativeWidget* source,
                     const ICoreMimePayload& payload,
                     const ICorePixmap& dragPixmap,
                     const ICorePoint& hotSpot = ICorePoint());
};
};

ICoreFontCatalog.h#

src/ICoreEssentials/UI/System/ICoreFontCatalog.h

ICoreFontCatalog#

ICoreFontCatalog.h:8 · class · 6 declaration(s)

The installed-fonts registry, as a static facade over QFontDatabase.

class ICoreFontCatalog {
public:
    ICoreFontCatalog() = delete;

    // The platform's fixed-pitch font (what code and terminals set).
    static ICoreFont fixedFont();

    // The application-wide default font (what an unstyled widget inherits) --
    // QApplication::font() behind the boundary. Added at E4: the canvas and
    // dialog labels all derive their fonts from it by nudging the point size.
    static ICoreFont applicationFont();

    static bool hasFamily(const ICoreString& family);

    // Every font family installed on this machine, for a font picker.
    static ICoreStringList families();

    // Register a bundled font file; returns false if the file was rejected.
    static bool addApplicationFont(const ICoreString& path);
};
};

ICoreMimePayload.h#

src/ICoreEssentials/UI/System/ICoreMimePayload.h

ICoreMimePayload#

ICoreMimePayload.h:12 · struct · 1 declaration(s)

What a drag (or clipboard interchange) carries, as a plain value.

struct ICoreMimePayload {
public:
    ICoreString text;

    ICoreStringList urls;

    ICoreString customFormat;
    std::string customData;

    // Out of line for the header surface rule (H4.53). The fields above stay:
    // they are PUBLIC, and this is a value struct whose content is its
    // contract -- the rule bans private and protected data, not public.
    [[nodiscard]] bool hasCustomFormat(const ICoreString& format) const;
};
};

ICorePlatform.h#

src/ICoreEssentials/UI/System/ICorePlatform.h

Which OS this build targets, without a client naming the toolkit's own platform macros. Exactly one of these is defined.

A macro rather than a constant because the call sites are #if branches around whole blocks -- code that only COMPILES on one platform (a registry path, a bundle layout) cannot be selected by a runtime test.

Declares no class of its own — see the file.

ICoreRenderingPolicy.h#

src/ICoreEssentials/UI/System/ICoreRenderingPolicy.h

ICoreRenderingPolicy#

ICoreRenderingPolicy.h:27 · class · nested Provider · 8 declaration(s)

ICoreRenderingPolicy -- the Essentials-side seam for rendering-budget choices that are application policy, not SDK policy (ESSENTIALS_INDEPENDENCE D3).

class ICoreRenderingPolicy {
public:
    struct Provider {
        std::function<bool()> canvasAnimationsEnabled;
        std::function<bool()> widgetAnimationsEnabled;
        std::function<int()>  animationDurationPercent;
        std::function<bool()> canvasShadowsEnabled;
        std::function<bool()> floatingPanelShadowsEnabled;
    };

    static void installProvider(Provider provider);

    // Each falls back to its default when the provider (or that one entry)
    // is absent: enabled / 100.
    static bool canvasAnimationsEnabled();
    static bool widgetAnimationsEnabled();
    static int  animationDurationPercent();
    static bool canvasShadowsEnabled();
    static bool floatingPanelShadowsEnabled();

    // Raised (synchronously, on the GUI thread) after the values above may
    // have changed. Essentials code that caches a policy-derived state
    // subscribes here; the host calls notifyChanged().
    static ICoreSignal<>& changed();
    static void notifyChanged();
};
};

ICoreScreen.h#

src/ICoreEssentials/UI/System/ICoreScreen.h

ICoreScreen#

ICoreScreen.h:8 · class · 5 declaration(s)

The monitors, as a static facade.

class ICoreScreen {
public:
    ICoreScreen() = delete;

    static ICoreRect primaryGeometry();
    static ICoreRect primaryAvailableGeometry();

    // The screen under `globalPos`, falling back to the primary one -- so the
    // answer is always a usable rect, never a "no screen" sentinel.
    static ICoreRect availableGeometryAt(const ICorePoint& globalPos);

    static double devicePixelRatio();
};
};

ICoreSystemAppearance.h#

src/ICoreEssentials/UI/System/ICoreSystemAppearance.h

ICoreSystemAppearance#

ICoreSystemAppearance.h:8 · class · 3 declaration(s)

What the OS says about its own look, as a static facade over QStyleHints.

class ICoreSystemAppearance {
public:
    ICoreSystemAppearance() = delete;

    static bool isDarkMode();

    // Fires on the GUI thread when the OS switches its colour scheme.
    static ICoreSignal<>& onChanged();
};
};

ICoreUiMetrics.h#

src/ICoreEssentials/UI/System/ICoreUiMetrics.h

ICoreUiMetrics#

ICoreUiMetrics.h:6 · class · 3 declaration(s)

Platform interaction constants, as a static facade.

class ICoreUiMetrics {
public:
    ICoreUiMetrics() = delete;

    // Pointer travel, in pixels, that turns a press into a drag.
    static int startDragDistance();

    // Maximum gap, in milliseconds, between the two clicks of a double-click.
    static int doubleClickIntervalMs();
};
};

ICoreUiTimer.h#

src/ICoreEssentials/UI/System/ICoreUiTimer.h

ICoreUiTimer#

ICoreUiTimer.h:13 · class · pImpl · 11 declaration(s)

The client-facing timer.

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

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

    void start(int intervalMs);
    void start();   // reuse the configured interval, like the toolkit's no-arg start
    void stop();
    bool isActive() const;

    void setSingleShot(bool singleShot);
    void setInterval(int intervalMs);
    int interval() const;

    ICoreSignal<> onTimeout;

    // Fire-and-forget delay. The scope gates delivery: if it dies first, the
    // callable never runs -- this is the safe spelling of the
    // QTimer::singleShot(ms, this, ...) idiom.
    static void singleShot(int delayMs, ICoreSignalScope& scope, std::function<void()> fn);

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

ICoreWeakObject.h#

src/ICoreEssentials/UI/System/ICoreWeakObject.h

ICoreWeakObject#

ICoreWeakObject.h:24 · class · 16 declaration(s)

A pointer to a toolkit-owned object that becomes null when the object dies.

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

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

    template <class T>
    ICoreWeakObject(T* object) : ICoreWeakObject() {
        assign(object);
    }

    template <class T>
    ICoreWeakObject& operator=(T* object) {
        assign(object);
        return *this;
    }

    [[nodiscard]] bool isNull() const;

    explicit operator bool() const;

    // Sound only for the type the handle was built from; the caller knows it,
    // and a dynamic check would need the pointee's definition, which is the
    // very thing this header avoids requiring.
    template <class T>
    T* as() const {
        return static_cast<T*>(object());
    }

    bool operator==(const ICoreWeakObject& other) const;

    bool operator!=(const ICoreWeakObject& other) const;

    void clear();

    // The seam the three templates above call. See the note on the class.
    void assign(QObject* object);
    [[nodiscard]] QObject* object() const;

    // Public only so the .cpp can pin them: one QPointer, measured on this
    // tree's Qt 6.10.2, macOS arm64.
    static constexpr std::size_t kNativeStorageSize = 16;
    static constexpr std::size_t kNativeStorageAlign = 8;

};

ICoreWeakWidget.h#

src/ICoreEssentials/UI/System/ICoreWeakWidget.h

ICoreWeakWidget#

ICoreWeakWidget.h:29 · class · 13 declaration(s)

A pointer to a widget that becomes null when the widget dies, for the "remember what I was anchored to" cases where the remembered widget may be destroyed first.

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

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

    ICoreWeakWidget(ICoreWidget* widget);

    ICoreWeakWidget& operator=(ICoreWidget* widget);

    [[nodiscard]] ICoreWidget* get() const;

    ICoreWidget* operator->() const;

    operator ICoreWidget*() const;   // QPointer's implicit conversion, kept

    explicit operator bool() const;

    bool operator==(const ICoreWidget* other) const;

    void clear();

    // Public only so the .cpp can pin them. Measured, not assumed:
    // QPointer<QWidget> is a QWeakPointer, {d-pointer, value} -- 16 bytes /
    // align 8 on this tree's Qt 6.10.2, macOS arm64 -- plus the cached wrapper
    // pointer.
    static constexpr std::size_t kNativeStorageSize = 24;
    static constexpr std::size_t kNativeStorageAlign = 8;

};

ICoreWeakAnyWidget#

ICoreWeakWidget.h:75 · class · 13 declaration(s)

The same guarantee for a widget this API does not get to choose -- the ICoreAnyWidget counterpart of ICoreWeakWidget.

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

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

    ICoreWeakAnyWidget(QWidget* widget);

    ICoreWeakAnyWidget& operator=(QWidget* widget);

    [[nodiscard]] QWidget* get() const;

    QWidget* operator->() const;

    explicit operator bool() const;

    bool operator==(const QWidget* other) const;

    void clear();

    // One QPointer, nothing cached beside it. See the note above.
    static constexpr std::size_t kNativeStorageSize = 16;
    static constexpr std::size_t kNativeStorageAlign = 8;

};

ICoreWeak#

ICoreWeakWidget.h:118 · class · 2 declaration(s)

class ICoreWeak {
public:
    ICoreWeak() = default;

    ICoreWeak(T* widget) { assign(widget); }

    ICoreWeak& operator=(T* widget) {
        assign(widget);
        return *this;
    }

    T* get() const { return m_native.isNull() ? nullptr : m_wrapper; }
    T* operator->() const { return get(); }
    operator T*() const { return get(); }   // QPointer's implicit conversion, kept
    explicit operator bool() const { return !m_native.isNull(); }
    void clear() { m_native = nullptr; m_wrapper = nullptr; }

};

ICoreWindowTracker.h#

src/ICoreEssentials/UI/System/ICoreWindowTracker.h

ICoreWindowTracker#

ICoreWindowTracker.h:22 · class · nested Hooks · 3 declaration(s)

ICoreWindowTracker -- the Essentials-side seam for application window bookkeeping (ESSENTIALS_INDEPENDENCE D2).

class ICoreWindowTracker {
public:
    struct Hooks {
        std::function<void(ICoreWidget*)> windowOpened;
        std::function<void(ICoreWidget*)> windowClosed;
    };

    static void installHooks(Hooks hooks);

    static void notifyWindowOpened(ICoreWidget* window);
    static void notifyWindowClosed(ICoreWidget* window);
};
};