API — ICoreEssentials/UI/Panels

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

ICoreApplyButtonsBar.h#

ICoreEssentials/UI/Panels/ICoreApplyButtonsBar.h

ICoreApplyButtonsBar#

ICoreApplyButtonsBar.h:12 · class · bases public ICoreWidget · pImpl · 4 declaration(s)

class ICoreApplyButtonsBar : public ICoreWidget {
public:
    explicit ICoreApplyButtonsBar(ICoreNativeWidget* parent = nullptr);

    ICoreButton* getCancelButton() const;
    ICoreButton* getOkButton() const;

    ~ICoreApplyButtonsBar() override;

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

ICoreCardPanel.h#

ICoreEssentials/UI/Panels/ICoreCardPanel.h

ICoreCardPanel#

ICoreCardPanel.h:35 · class · bases public ICoreWidget · pImpl · 7 declaration(s)

Wraps a page widget in a white rounded card with a gap around it, for use as a page of one of the sliding menu panels.

class ICoreCardPanel : public ICoreWidget {
public:
    // Takes ownership of `content` by reparenting it into the card.
    // Narrowed with P6.1: all six call sites pass an ICoreWidget subclass, and
    // the raw type was only widening it at the boundary.
    explicit ICoreCardPanel(ICoreWidget* content, ICoreNativeWidget* parent = nullptr);

    // The wrapped page, for callers holding only the card.
    ICoreWidget* getContent() const;

    // Gap between the card and whatever hosts it. Defaults to the shared inset.
    void setInset(int inset);

    // Take surface.panelRecessed instead of surface.panelRaised.
    //
    // For a page that brings its own bright surface with it -- the Terminal
    // panel's grid paints the editor's white over most of the card -- where a
    // raised white card leaves the chrome around that surface with no ground of
    // its own to sit on. Only the light theme moves; the dark theme spells the
    // two tokens the same value.
    //
    // A per-card switch rather than a colour argument on purpose: the card
    // re-reads its token on every theme change, and a colour handed in once
    // would be frozen at whichever theme was live when the card was built.
    void useRecessedSurface(bool recessed);

    // Declared here, DEFINED in the .cpp -- destroying a unique_ptr<Impl>
    // needs Impl complete, and in this header it is not.
    ~ICoreCardPanel() override;

protected:
    // Passed on to the wrapped page. A card is what a stack holds, so a stack
    // raising it tells the CARD -- and a page that does its work when it is
    // shown (Git, Terminal, the math tools) would never hear it otherwise.
    void shown() override;
    void hidden() override;

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

ICoreCollapsableOpenHeight.h#

ICoreEssentials/UI/Panels/ICoreCollapsableOpenHeight.h

How tall an ICoreCollapsableWidget opens: one rule for every seat.

⚠⚠ THE RULE WAS APPKIT'S ALONE, AND WINDOWS OPENED EVERY LIBRARY FAMILY TO 300 PIXELS (W10.47). The block library's family stacks are built on an ICoreFlowLayout -- a wall of tiles that wraps into as many rows as the width allows -- so their height is a function of their width. The AppKit seat learned to measure the body AT THE SECTION'S WIDTH before opening (naturalOpenHeight), and to re-measure when that width moves; the WinUI seat kept the constructor's default, and every family with more than 300 pixels of tiles opened short, with the family below drawn over its last rows.

So the order of the questions lives here and a seat supplies only the one thing it alone can answer -- heightForWidth, "how tall would this body's layout be at this width" (0 when it cannot say). In order:

Declares no class of its own — see the file.

ICoreCollapsableWidget.h#

ICoreEssentials/UI/Panels/ICoreCollapsableWidget.h

ICoreCollapsableWidget#

ICoreCollapsableWidget.h:15 · class · bases public ICoreWidget · pImpl · 7 declaration(s)

class ICoreCollapsableWidget : public ICoreWidget {
public:
    explicit ICoreCollapsableWidget(ICoreNativeWidget* parent = nullptr, ICoreWidget* contentWidget = new ICoreWidget(), const std::string& tagText = "Tag");

    void setCollapsed(bool collapsed);

    // The same state change with no animation, for setting a section's STARTING
    // shape. setCollapsed() animates from the content's current maximumHeight,
    // which for a section that has never been opened is QWIDGETSIZE_MAX -- so
    // collapsing one at construction spends almost all of its 250 ms above the
    // content's real height, appearing to do nothing and then snapping shut.
    void setCollapsedImmediately(bool collapsed);

    bool getIsCollapsed() const;

    // Whether setCollapsed() eases the fold or performs it outright.
    //
    // ⚠ ON BY DEFAULT, which is what every existing call site already gets.
    // setCollapsedImmediately() is unaffected: it has always been the "no
    // travel" spelling and stays the one to reach for when a section is being
    // given its STARTING shape rather than being folded by a user.
    //
    // ⚠ WHY IT IS WORTH A SWITCH RATHER THAN A POLICY. A fold re-runs every
    // layout above the section on every frame it steps through -- that is what
    // a height animation IS on a backend whose layouts are driven rather than
    // constraint-solved -- so a section deep inside a scroll pane on a busy
    // page pays for it. A caller who is folding six sections at once, or
    // restoring a saved layout, wants them to arrive rather than to race.
    void setAnimated(bool animated);
    [[nodiscard]] bool isAnimated() const;

    ~ICoreCollapsableWidget() override;

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

ICoreCollapsableWidgetTopBar.h#

ICoreEssentials/UI/Panels/ICoreCollapsableWidgetTopBar.h

ICoreCollapsableWidgetTopBar#

ICoreCollapsableWidgetTopBar.h:14 · class · bases public ICoreWidget · pImpl · 7 declaration(s)

class ICoreCollapsableWidgetTopBar : public ICoreWidget {
public:
    explicit ICoreCollapsableWidgetTopBar(ICoreWidget* parent = nullptr, ICoreCollapsableWidget* parentSyntraWidget = nullptr, const std::string& tagName = "Tag");

    ICoreRotatableArrowIcon* getArrowIconContainer() const;

    ~ICoreCollapsableWidgetTopBar() override;

protected:
    void paintContent(ICorePainter& painter) override;
    void pointerEntered() override;
    void pointerLeft() override;
    bool mousePressed(const ICoreMouseEvent& event) override;

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

ICoreDecoratedWindow.h#

ICoreEssentials/UI/Panels/ICoreDecoratedWindow.h

The air around the rail and the page, for a window configured as a toggle panel. See ICoreTogglePanel::setContentMargins; a no-op on a window that is not one.

ICoreDecoratedWindow#

ICoreDecoratedWindow.h:17 · class · bases public ICoreWidget · pImpl · 17 declaration(s)

class ICoreDecoratedWindow : public ICoreWidget {
public:
    explicit ICoreDecoratedWindow(const bool& configureAsTogglePanel = false);

    ICoreTogglePanelButton* createNewToggleMenu(ICoreWidget *contentWidget, const std::string &title, const ICoreIcon &icon) const;

    void toggle(ICoreTogglePanelButton *buttonToToggle) const;

    void toggleToFirst() const;

    void hideCancelOkButtons() const;

    void setLeftFixedPanelWidth(const int &newWidth) const;

    // The air around the rail and the page, for a window configured as a toggle
    // panel. See ICoreTogglePanel::setContentMargins; a no-op on a window that
    // is not one.
    void setContentMargins(const ICoreMargins& margins, int spacing) const;

    // Spans the full width of the window, above the left panel and content area.
    // ⚠ ONE function now, not a QMargins/ICoreMargins pair: the pair existed so a
    // client outside the wrapper zone need not spell the toolkit margin type, and
    // the only caller was already passing ICoreMargins. Collapsing it takes a raw
    // QMargins out of an ICoreEssentials header.
    void addTopBarWidget(ICoreNativeWidget* widget,
                         const ICoreMargins& margins = ICoreMargins(15, 15, 15, 0)) const;

    void addAuxiliaryPage(ICoreNativeWidget* page) const;
    void showPage(ICoreNativeWidget* page) const;
    ICoreNativeWidget* getCurrentPage() const;

    const std::vector<ICoreTogglePanelButton*>& getToggleButtons() const;

    ICoreWidget* getLeftFixedPanel() const;
    ICoreWidget* getRightContentArea() const;

    ICoreButton *getCancelButton() const;

    ICoreButton *getOkButton() const;

    ~ICoreDecoratedWindow() override;

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

ICoreMenuChooserPanel.h#

ICoreEssentials/UI/Panels/ICoreMenuChooserPanel.h

ICoreMenuChooserPanel#

ICoreMenuChooserPanel.h:12 · class · bases public ICoreWidget · pImpl · 4 declaration(s)

class ICoreMenuChooserPanel : public ICoreWidget {
public:
    explicit ICoreMenuChooserPanel(ICoreNativeWidget* parent = nullptr);

    void addNewMenu(const std::string& menuTitle, ICoreNativeWidget* menu);

    void setFocusOnFirst();

    ~ICoreMenuChooserPanel() override;

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

ICoreSplitPane.h#

ICoreEssentials/UI/Panels/ICoreSplitPane.h

ICoreSplitPane#

ICoreSplitPane.h:32 · class · bases public ICoreWidget · pImpl · 9 declaration(s)

A composite: a splitter filling a widget, with an optional scroll pane wrapped around any pane that asks for one.

class ICoreSplitPane : public ICoreWidget {
public:
    // ICoreOrientation is value-pinned to Qt::Orientation in
    // ICoreInputEnumsVerify.cpp, so the Qt backend's cast to the toolkit enum
    // is a static_assert rather than a convention. Vertical stays the default,
    // and stays the same VALUE (2).
    explicit ICoreSplitPane(ICoreOrientation orientation = ICoreOrientation::Vertical,
                            ICoreNativeWidget* parent = nullptr);

    // Declared here, DEFINED in the backend's .cpp -- destroying a
    // unique_ptr<Impl> needs Impl complete, and in this header it is not.
    ~ICoreSplitPane() override;

    // Append or insert a pane.
    //
    // ⚠ `scrollable` DECIDES WHO OWNS THE PANE WIDGET, and the two answers are
    // opposite. A plain pane stays the CALLER's: this class only reparents it,
    // and removing it or destroying the split pane leaves it alive. A
    // scrollable pane is wrapped in an ICoreScrollPane, and that class takes
    // ownership of whatever it is given ("the pane deletes it" -- its own
    // header) -- so the widget passes to this class transitively, and removing
    // the pane DESTROYS IT.
    //
    // The asymmetry is not new and is not a choice made here; it is what
    // ICoreScrollPane's contract has always meant for this composite. It was
    // invisible because the scroll pane used to be leaked, so nothing was ever
    // destroyed at all. Stated rather than smoothed over, because the two
    // plausible ways to smooth it -- never owning, or always owning -- each
    // mean changing a contract in a class that belongs to another row.
    //
    // A widget can only be in one pane at a time: handing over one this split
    // pane already holds MOVES it rather than adding a second entry.
    void addPane(ICoreNativeWidget* paneWidget, bool scrollable);
    void insertPane(int index, ICoreNativeWidget* paneWidget, bool scrollable);

    // Take a pane out. A plain pane's widget survives; a scrollable pane's does
    // not, per the ownership note above -- the scroll pane goes and takes its
    // content with it.
    //
    // ⚠ THE SAME IS TRUE OF DESTROYING THE SPLIT PANE, AND IT TOOK A
    // DESTRUCTOR COUNTER TO ESTABLISH IT. The two backends disagreed: on Qt the
    // plain pane had been reparented into the splitter and the toolkit's object
    // tree reaped it, so a widget the caller still held a pointer to was freed
    // on one platform and not the other. They agree now -- a plain pane is
    // unparented before teardown on both -- but the rule is stated here rather
    // than left to be rediscovered, because "not crashing" is what it looked
    // like from the outside.
    void removePane(int index);
    void clearPanes();

    int count() const;

    // The container actually held at `index`: the pane widget itself, or the
    // scroll pane wrapped around it. Null for an index that is not a pane.
    ICoreNativeWidget* widgetAt(int index) const;

    // The splitter underneath, for a call site that needs to set a stretch
    // factor or listen for a drag.
    ICoreSplitter* splitter() const;

    void setInitialSizes(const std::vector<int>& sizes);

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

ICoreTogglePanel.h#

ICoreEssentials/UI/Panels/ICoreTogglePanel.h

The air around the rail and the content area, together. The default is 15 on all four sides with 15 between the two, which is what a settings dialog wants; a page whose content is a dense grid of its own -- the block library -- asks for less, or none.

⚠ IT IS THE PANEL'S OWN ROOT ROW, not the content area's layout: the padding a caller sees around the right-hand page is the ROW's margin plus its spacing, and a margin set on the page inside it cannot remove either.

ICoreTogglePanel#

ICoreTogglePanel.h:20 · class · bases public ICoreWidget · pImpl · 18 declaration(s)

class ICoreTogglePanel : public ICoreWidget {
public:
    explicit ICoreTogglePanel(ICoreNativeWidget* parent = nullptr, const bool& designOkCancelButtons = false);

    ICoreTogglePanelButton* createNewToggleMenu(ICoreWidget* contentWidget, const std::string &title, const ICoreIcon &icon);

    void clearAll();

    void toggle(ICoreTogglePanelButton* button) const;

    void toggleToFirst() const;

    void hideCancelOkButtons() const;

    void setEmptyPromptText(const std::string& text) const;

    // The air around the rail and the content area, together. The default is
    // 15 on all four sides with 15 between the two, which is what a settings
    // dialog wants; a page whose content is a dense grid of its own -- the
    // block library -- asks for less, or none.
    //
    // ⚠ IT IS THE PANEL'S OWN ROOT ROW, not the content area's layout: the
    // padding a caller sees around the right-hand page is the ROW's margin plus
    // its spacing, and a margin set on the page inside it cannot remove either.
    void setContentMargins(const ICoreMargins& margins, int spacing) const;

    // Pages that live in the content stack without owning a toggle button
    // (e.g. a cross-category search result view).
    void addAuxiliaryPage(ICoreNativeWidget* page) const;
    void showPage(ICoreNativeWidget* page) const;
    ICoreNativeWidget* getCurrentPage() const;

    const std::vector<ICoreTogglePanelButton*>& getAllButtons() const;

    ICoreWidget* getLeftFixedPanel() const;

    // The colour the left panel outlines itself in, asked on every paint so it
    // follows a theme switch. Unset, the panel takes the theme's hairline like
    // any other panel; a window that dresses the left panel as a rail of its own
    // hands in that rail's rim colour so the edge matches what continues it.
    void setLeftPanelBorderColor(std::function<ICoreColor()> color) const;

    // Narrowed with P6.1: the member has always been an ICoreWidget*, so the
    // QWidget* return was widening it back at the boundary for no reason and
    // forcing every caller to hold the raw type.
    ICoreWidget* getRightContentArea() const;

    ICoreButton* getCancelButton() const;
    ICoreButton* getOkButton() const;

    ~ICoreTogglePanel() override;

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

ICoreTogglePanelButton.h#

ICoreEssentials/UI/Panels/ICoreTogglePanelButton.h

ICoreTogglePanelButton#

ICoreTogglePanelButton.h:16 · class · bases public ICoreWidget · pImpl · 10 declaration(s)

class ICoreTogglePanelButton : public ICoreWidget {
public:
    explicit ICoreTogglePanelButton(ICoreNativeWidget* parent, ICoreTogglePanel* parentPanel, ICoreWidget* contentWidget);

    void setIcon(const ICoreIcon& icon) const;

    void setTitle(const ICoreString& title) const;

    void setHoldSelectedStyle(const bool& newValue);

    ICoreWidget* getContentWidget() const;

    // Out of line: m_hoverAnimation's unique_ptr needs the complete type there.
    ~ICoreTogglePanelButton() override;

protected:
    // The hover treatment is painted rather than styled, so it can animate and
    // carry the accent edge. See the paint order in the .cpp.
    void pointerEntered() override;

    void pointerLeft() override;

    void paintContent(ICorePainter& painter) override;

    bool mousePressed(const ICoreMouseEvent& event) override;

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

ICoreToolBar.h#

ICoreEssentials/UI/Panels/ICoreToolBar.h

ICoreToolBar#

ICoreToolBar.h:36 · class · bases public ICoreWidget · pImpl · 10 declaration(s)

⚠⚠ THE BAR CLIPS ITS CHILDREN TO ITS OWN FRAME, AND HAS SINCE W10.92 (2026-09-21).

class ICoreToolBar : public ICoreWidget {
public:
    // ICoreNativeWidget*, REPLACING the old QWidget* rather than overloading
    // it (P5.10). An overload would be R4-ambiguous for every ICoreWidget*
    // argument, which is most of the call sites -- and a constructor cannot
    // take a distinct name the way subscribeNative could. Replacement is
    // unambiguous forever and is the signature this class ends up with anyway
    // once ICoreWidget's own constructor takes the interface.
    explicit ICoreToolBar(ICoreNativeWidget* parent = nullptr);

    void addWidget(ICoreNativeWidget *widget) const;

    void addStretch() const;

    // The tool bar's own row layout, reached by name rather than through
    // QWidget::layout(). These exist because the layout is built by THIS
    // constructor, so a consumer configuring it had no handle to it and
    // reached back through the toolkit -- the ~28-site escape seam P6.6 owns.
    //
    // ⚠ Both were declared with EMPTY BODIES by the Phase 0 seam prep and one
    // caller (ICoreChartToolBar) had already been migrated onto them, so that
    // tool bar silently ran with the base's 15/8/15/8 margins and spacing 10
    // from e3196e55 until P6.6 implemented them. A named forwarder that
    // compiles is not a named forwarder that works.
    //
    // ⚠ The margins parameter is ICoreMargins and must NOT go back to
    // ICoreRect: a rect is (x, y, w, h) and its right()/bottom() ADD, so the
    // ICoreRect(15, 0, 15, 0) the old signature invited reads out as
    // right() == 30. ICoreMargins already existed and already means exactly
    // these four numbers.
    void setLayoutContentsMargins(const ICoreMargins &newMargins);

    void setLayoutSpacing(int newSpacing);

    // Drops the constructor's Qt::AlignLeft so the row's content fills the bar
    // instead of packing to the left. Named rather than a setAlignment cover:
    // clearing is the only thing any call site does, and an alignment enum
    // crossing the boundary is what P6.4 records as a hole neither guard sees.
    void clearLayoutAlignment();

    // Spread fillColor() as ICoreSurfaceGradient's ramp -- lit at the corner
    // `direction` names, deepening toward the opposite one -- instead of one
    // flat wash. Off by default, and it changes only the SPREAD: fillColor()
    // still names the ground, so an override that follows the theme keeps
    // following it.
    //
    // The two strengths scale how far each end of the ramp travels from that
    // colour, separately, so the lit end can be brought down without the deep
    // end coming up with it. A bar is a fortieth of a fixed panel's height, so
    // the same ramp across one is a far steeper slope and reads as a gloss
    // highlight rather than as the flat-lit material the panels wear -- which
    // is what they are for. ICoreWidget carries the same four for a
    // Surface::Panel body.
    void setGradientFill(bool gradient,
                         ICoreGradientDirection direction = ICoreGradientDirection::TopToBottom,
                         double litStrength = 1.0,
                         double deepStrength = 1.0);

    // The same treatment for the bar's OUTLINE, on a border-tuned ramp
    // (ICoreSurfaceGradient::forBorder) rather than the fill's -- the travel
    // that reads as material across a body is invisible along a hairline.
    // Off by default, so every bar in the tree keeps the flat rim it has.
    //
    // Meant to be given the direction the fill already runs: the bar and its
    // rim then take the light from the same place, which is the whole point of
    // asking for it.
    void setGradientBorder(bool gradient,
                           ICoreGradientDirection direction = ICoreGradientDirection::TopToBottom,
                           double litStrength = 1.0,
                           double deepStrength = 1.0);

    // How thick the rim is drawn, in pixels. 1.0 is a bar's hairline; 2.0 is
    // what a Surface::Panel body wears, and is what a bar asks for when it sits
    // among the fixed panels rather than inside one.
    //
    // The body's rounded path is inset by HALF of this, so the stroke lands
    // entirely inside the widget. That is not decoration: a pen is centred on
    // its path, so a 2px rim on the 0.5px inset a hairline wants would put half
    // its width outside the bar's own bounds, where it is clipped -- which
    // reads as a 1px border with hard corners rather than as a thicker one.
    void setBorderWidth(double width);

    // Declared here, DEFINED in the .cpp -- destroying a unique_ptr<Impl>
    // needs Impl complete, and in this header it is not.
    ~ICoreToolBar() override;

protected:
    void paintContent(ICorePainter& painter) override;

    // The body's fill, read at paint time so it follows the theme with no work
    // of its own. Defaults to the raised-surface token, which is defined on
    // both themes -- white on the light one, g850 on the dark one. A subclass
    // that wants a different ground overrides this; returning
    // ICoreColor::transparent() is how one opts out and shows what is behind it.
    //
    // ⚠ This is the ONLY thing that fills the body. The constructor used to
    // stamp the same colour as an auto-filled background and as a stylesheet
    // too; both are gone, because the first squares off the rounded corners and
    // the second cascades onto every child widget in the row.
    virtual ICoreColor fillColor() const;

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