API — ICoreEssentials/UI/Backends/Web/Windows

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

ICoreWebCaption.h#

ICoreEssentials/UI/Backends/Web/Windows/ICoreWebCaption.h

The caption strip of a decorated web window: where its own buttons go, which one a point is on, and how the default strip is painted (web backend, WB3.4).

⚠ THE BUTTONS FOLLOW THE HOST'S CONVENTION, not a web one: on a Mac page the close and zoom lights sit at the LEFT, elsewhere a maximise and a close sit at the right. A page is on someone's desktop, and the window chrome that user already knows is the one to draw.

⚠ THERE IS NO MINIMISE BUTTON. A minimised window is a hidden one, and a page has no taskbar or dock to bring it back from, so offering one would be a way to lose a window. ICoreWebWindow::minimize() still exists for callers.

Backend-private: include it from a .cpp inside UI/Backends/Web/ and nowhere else.

ICoreWebCaptionLayout#

ICoreWebCaption.h:28 · struct · 0 declaration(s)

struct ICoreWebCaptionLayout {
public:
    ICoreRect close;
    ICoreRect maximize;
    int insetLeft = 0;    // the strip each end's buttons cover, px
    int insetRight = 0;
    bool lights = false;  // drawn as macOS traffic lights
};
};

ICoreWebCaptionState#

ICoreWebCaption.h:43 · struct · 0 declaration(s)

struct ICoreWebCaptionState {
public:
    std::string title;
    bool active = true;
    bool maximized = false;
    ICoreWebCaptionButton hovered = ICoreWebCaptionButton::None;
    ICoreWebCaptionButton pressed = ICoreWebCaptionButton::None;
    // Invalid = the theme's.
    ICoreColor foreground;
    ICoreColor hoverBackground;
    ICoreColor pressedBackground;
    ICoreColor inactiveForeground;
};
};

File-scope declarations#

enum class ICoreWebCaptionButton { None, Close, Maximize };

ICoreWebPromptSeat.h#

ICoreEssentials/UI/Backends/Web/Windows/ICoreWebPromptSeat.h

The web backend's one <dialog> builder, shared by the prompts (ICoreWebPrompts.cpp, WB3.1) and the pickers (ICoreWebPickers.cpp, WB3.2). Backend-private: nothing outside UI/Backends/Web/ includes it.

A prompt answers ONCE, later, through the frame loop (ICoreMainThread::post): code is 1 for the affirmative, 0 for cancel / Escape, 2 for Don't Save, 3 for No; value is set only for an affirmative answer of a prompt that has fields.

File-scope declarations#

enum class ICoreWebPromptKind : int {
    Notify = 0,
    Question = 1,
    Confirm = 2,
    SaveDiscardCancel = 3,
    Text = 4,
    Item = 5,
    Color = 6,      // initial "#rrggbb"; value "#rrggbb"
    Font = 7,       // items = suggested families; initial and value "family\x1fsize\x1fbold\x1fitalic"
    SaveName = 8,   // initial = suggested name; items = filter labels; value "name\x1ffilterIndex"
};

using ICoreWebPromptDelivery = std::function<void(int code, std::optional<std::string> value)>;

ICoreWebTitleBarSeat.h#

ICoreEssentials/UI/Backends/Web/Windows/ICoreWebTitleBarSeat.h

ICoreWebTitleBarSeat#

ICoreWebTitleBarSeat.h:27 · class · bases public ICoreTitleBarHost · pImpl · 13 declaration(s)

The web seat for ICoreTitleBar, shared by ICoreWindow and ICoreDialog (web backend, WB3.4) -- ICoreGtk4TitleBarSeat's shape.

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

    // The explicit choice; nullptr keeps the window's own painted caption.
    // Either opts out of ICoreTitleBarProvider.
    void setBar(ICoreTitleBar* bar);
    [[nodiscard]] ICoreTitleBar* bar() const;

    // Ask ICoreTitleBarProvider once, before the first show of a decorated window.
    void adoptDefaultIfNeeded();

    void titleBarBeginMove() override;
    void titleBarDoubleClicked() override;
    void titleBarMinimize() override;
    void titleBarToggleMaximize() override;
    void titleBarClose() override;
    void titleBarChanged() override;

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

ICoreWebTouchRouter.h#

ICoreEssentials/UI/Backends/Web/Windows/ICoreWebTouchRouter.h

ICoreWebPointerSample#

ICoreWebTouchRouter.h:71 · struct · 0 declaration(s)

Tablet port, TB1.6 -- where a finger or a pen on a web window goes: to a touch seat, to the gesture recogniser, or down the mouse path exactly as it did before touch existed.

struct ICoreWebPointerSample {
public:
    int type = 0;                  // 0 down, 1 up, 2 move, 3 cancel
    int pointerId = 0;
    ICorePointerKind kind = ICorePointerKind::Touch;   // Touch or Pen
    double x = 0.0;                // ROOT coordinates
    double y = 0.0;
    int button = 0;                // the DOM's own, passed to the mouse path verbatim
    int buttons = 0;
    unsigned int modifiers = 0;    // ICoreKeyModifier bits
    int detail = 0;
    double pressure = 0.0;
    double timeMs = 0.0;
};
};

ICoreWebTouchRouter#

ICoreWebTouchRouter.h:85 · class · pImpl · 10 declaration(s)

class ICoreWebTouchRouter {
public:
    // The window's existing mouse path: type 0 down, 1 up, 2 move, with the
    // arguments domPointerDown/Up/Move take. Returns the listener's answer.
    using MouseFn = std::function<bool(int type, double x, double y, int button, int buttons,
                                       unsigned int modifiers, int detail)>;
    // "Call tick() in `delayMs`"; a negative delay withdraws the request.
    using TimerFn = std::function<void(double delayMs)>;

    ICoreWebTouchRouter(MouseFn mouse, TimerFn timer);
    ~ICoreWebTouchRouter();
    ICoreWebTouchRouter(const ICoreWebTouchRouter&) = delete;
    ICoreWebTouchRouter& operator=(const ICoreWebTouchRouter&) = delete;

    // One touch or pen event. `pageX/pageY` is the root's origin on the page,
    // for the global positions. Returns whether the listener should
    // preventDefault().
    bool pointer(ICoreWebNode* root, const ICoreWebPointerSample& sample, double pageX, double pageY);

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

    // Forget the sequence in progress without delivering anything: the window
    // was hidden or destroyed under the fingers. A held hover and a shown
    // tooltip are taken down.
    void reset();

    // ---- TB1.7: the long press's hover and tooltip -------------------------
    // A setter rather than a constructor argument, so a window that shows no
    // tooltip (Android's page, today) need not pass one. Empty text: hide.
    using ToolTipFn = std::function<void(const std::string& text, double pageX, double pageY)>;
    void setToolTipHook(ToolTipFn toolTip);

    // A real mouse moved or pressed on this window: a finger's held hover and
    // its tooltip give way to it.
    void noteMouseActivity();

    // Whether a long press's hover is being held after its lift -- while it is,
    // a touch's `pointerleave` must not clear the hover.
    [[nodiscard]] bool holdsHover() const;

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

ICoreWebWindow.h#

ICoreEssentials/UI/Backends/Web/Windows/ICoreWebWindow.h

The web backend's top-level window: one <canvas> element in the page, and the host of one ICoreWebNode tree.

⚠ ITS SURFACE IS ICoreGtk4Window's (UI/Backends/Gtk4/Windows/ICoreGtk4Window.h) WITH THE TOOLKIT TYPES TAKEN OUT, because the widget and ICoreWindow seats of this backend are the GTK4 seats' logic and call it the same way.

⚠⚠ THE WINDOW MODEL: EVERY WINDOW IS ITS OWN CANVAS ELEMENT, absolutely positioned in the page's root container (#icore-root in the product shell, the body in a rig page), stacked by CSS z-order. The browser composites the windows and decides which one a pointer is over, so a window only has to route input within itself; each canvas's own DOM listeners feed its ICoreWebInputRouter. The page is the "screen" (ICoreScreen answers the viewport), and a window's position is its CSS left/top in it.

ICoreWebWindow#

ICoreWebWindow.h:51 · class · bases public ICoreWebNodeHost · pImpl · 68 declaration(s)

class ICoreWebWindow : public ICoreWebNodeHost {
public:
    ICoreWebWindow();
    ~ICoreWebWindow() override;

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

    // The canvas this window paints into; 0 where the realm has no DOM (node).
    [[nodiscard]] int canvas() const;

    // The root of the tree this window shows. The window becomes its host and
    // sizes it to the content size.
    void setChild(ICoreWebNode* child);
    [[nodiscard]] ICoreWebNode* child() const;

    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;
    // Where the window's content (0, 0) is in the page. A window never moved
    // is centred in the viewport the first time it is shown.
    void move(int x, int y);
    void position(int& x, int& y) const;

    void show();
    void hide();
    void present();               // show + raise + take the keyboard, as GTK4 fuses them
    void close();                 // asks the closing hook first
    void maximize();              // fills the viewport
    [[nodiscard]] bool isMaximized() const;
    void minimize();              // hidden, and remembered as minimised
    [[nodiscard]] bool isMinimized() const;
    [[nodiscard]] bool isVisible() const;
    [[nodiscard]] bool isActive() const;
    void setTitle(const std::string& title);
    [[nodiscard]] std::string title() const;
    void setDecorated(bool decorated);
    [[nodiscard]] bool isDecorated() const;

    // ---- the caption of a decorated window (WB3.4) ----------------------------
    // The strip's height: 0 for a window that has none (frameless, popup, card,
    // or not decorated), the hosted node's height when one is set, and the
    // default caption's otherwise.
    [[nodiscard]] int captionHeight() const;
    // Hosts `node` as the caption's root at `height` px (an ICoreTitleBar's
    // node); null goes back to the default painted caption. The window does not
    // own it.
    void setCaptionNode(ICoreWebNode* node, int height);
    [[nodiscard]] ICoreWebNode* captionNode() const;
    // The strips the window's own caption buttons cover, at each end, in px.
    void captionInsets(int& left, int& right) const;
    // Colours for the window's own caption buttons; an invalid one keeps the
    // theme's.
    void setCaptionButtonColors(const ICoreColor& foreground, const ICoreColor& hover,
                                const ICoreColor& pressed, const ICoreColor& inactive);
    // Fires when anything a caption shows changed: title, active, maximised,
    // insets.
    void setCaptionStateHook(std::function<void()> hook);
    // Moves the window with the pointer from the press being delivered now until
    // its release -- what a title bar's empty area asks for.
    void beginCaptionMove();
    void toggleMaximize();        // maximize(), or back to where it was
    void restore();
    // Repaints the caption at the next frame (a hosted node asked, or its look
    // changed).
    void repaintCaption();
    void setOpacity(double opacity);
    void setNature(ICoreWebWindowNature nature);
    [[nodiscard]] ICoreWebWindowNature nature() const;
    void setTransientFor(ICoreWebWindow* parent);
    [[nodiscard]] ICoreWebWindow* transientFor() const;
    void setModal(bool modal);
    [[nodiscard]] bool isModal() const;
    void setDismissedHook(std::function<void()> hook);

    [[nodiscard]] double devicePixelRatio() const override;
    [[nodiscard]] static int screenCount();

    void setClosingHook(std::function<bool()> hook);
    void setActivatedHook(std::function<void()> hook);
    void setShownHook(std::function<void()> hook);
    void setResizedHook(std::function<void(int contentWidth, int contentHeight)> hook);
    void setScaleChangedHook(std::function<void(double)> hook);
    // A key no widget handled reaches the window here; true stops the browser
    // acting on it too.
    void setKeyPressedHook(std::function<bool(const ICoreWebKeyInput&)> hook);

    // Paints now if dirty. The frame-end hook calls it for every window; a rig
    // calls it to paint without a frame loop.
    void paintIfDirty();
    [[nodiscard]] bool isDirty() const;

    // The shortcut seat's entry point: offered every key press before the
    // widgets are, and returns whether a shortcut took it. One per process.
    using ShortcutDispatcher = bool (*)(ICoreWebNode* root, const ICoreWebKeyInput& key);
    static void setShortcutDispatcher(ShortcutDispatcher dispatcher);

    // Every live window, and the one that last took a press or was presented.
    [[nodiscard]] static std::vector<ICoreWebWindow*> windows();
    [[nodiscard]] static ICoreWebWindow* activeWindow();

    // ---- ICoreWebNodeHost --------------------------------------------------
    void nodeNeedsRepaint(ICoreWebNode* root, const ICoreRect& area) override;
    void rootOrigin(double& x, double& y) const override;
    void cursorChanged(const std::string& css) override;
    void tooltipChanged(const std::string& text) override;

    // ---- DOM input, from the canvas's listeners. Coordinates are CSS pixels
    // relative to the canvas. Each returns whether the event was handled, so
    // the listener knows whether to preventDefault().
    bool domPointerDown(double x, double y, int button, int buttons, unsigned int modifiers,
                        int detail);
    bool domPointerUp(double x, double y, int button, int buttons, unsigned int modifiers);
    bool domPointerMove(double x, double y, int buttons, unsigned int modifiers);
    void domPointerLeave();
    bool domWheel(double x, double y, double deltaX, double deltaY, int deltaMode,
                  unsigned int modifiers);
    bool domKey(bool down, const std::string& key, const std::string& code, bool shift,
                bool ctrl, bool alt, bool meta, bool repeat);
    void domFocus(bool focused);
    // The caption canvas's listeners; coordinates relative to the caption.
    bool domCaptionPointerDown(double x, double y, int button, int buttons,
                               unsigned int modifiers, int detail);
    bool domCaptionPointerUp(double x, double y, int button, int buttons, unsigned int modifiers);
    bool domCaptionPointerMove(double x, double y, int buttons, unsigned int modifiers);
    void domCaptionPointerLeave();
    // A touch or pen pointer on the body canvas (tablet port, TB1.6).
    // `kind` is ICorePointerKind; the rest is the DOM event's, verbatim, so a
    // sequence no touch handler takes reaches domPointerDown/Up/Move exactly as it did before
    // (ICoreWebTouchRouter.h has the rules). `type` is 0 down, 1 up, 2 move, 3
    // cancel.
    bool domTouch(int type, int pointerId, int kind, double x, double y, int button, int buttons,
                  unsigned int modifiers, int detail, double pressure, double timeMs);
    // The touch router's long-press timer fired.
    void domTouchTick();
    // TB1.7: a real mouse pressed or moved on this window (the mouse listener,
    // never a finger's), so a finger's held hover and tooltip give way.
    void domMouseActivity();
    // TB1.7: whether a finger's long-press hover is being held after its lift;
    // a touch's `pointerleave` must not clear it while it is.
    [[nodiscard]] bool domTouchHoldsHover() const;

    // The canvas of the caption; 0 while the window has none, or no DOM.
    [[nodiscard]] int captionCanvas() const;

    // ⚠ MODALITY WITHOUT A NESTED LOOP: while a visible modal window is up, a
    // press, wheel or key on any window below it is refused and brings the modal
    // one forward. Exempt: popups, floating cards, and a window transient for
    // the modal one (its own child dialog). Null when nothing blocks `target`.
    [[nodiscard]] static ICoreWebWindow* modalBlocker(const ICoreWebWindow* target);

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

File-scope declarations#

enum class ICoreWebWindowNature {
    DecoratedWindow,
    FramelessWindow,
    Popup,
    FloatingCard,
};

ICoreWebWindowGeometry.h#

ICoreEssentials/UI/Backends/Web/Windows/ICoreWebWindowGeometry.h

The web backend's copy of UI/Backends/Gtk4/Windows/ICoreGtk4WindowGeometry.h, which names no toolkit: the saveGeometry()/restoreGeometry() text format. Its reasoning is in that file.

ICoreWebWindowGeometry#

ICoreWebWindowGeometry.h:9 · struct · 0 declaration(s)

struct ICoreWebWindowGeometry {
public:
    int width = 0;
    int height = 0;
    int screenCount = 0;
    bool maximized = false;
};
};