API — ICoreSDK/ICoreStudio/StudioObjects/Panels/LibraryNavigator

The public contract of 6 header(s) under src/ICoreSDK/ICoreStudio/StudioObjects/Panels/LibraryNavigator — 6 class/struct definition(s), 46 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICoreLibraryNavigator.h#

src/ICoreSDK/ICoreStudio/StudioObjects/Panels/LibraryNavigator/ICoreLibraryNavigator.h

The ready-made subsystems (ICoreTemplateLibrary), as their own category beside the block families. They are dragged onto a canvas exactly like a block, so this is where a user looks for them -- a template is a thing you reach for while building, which is what the library IS.

Bundle templates are left out: those are whole projects, and belong to the New Project form rather than to a palette you drop onto a diagram.

ICoreLibraryNavigator#

ICoreLibraryNavigator.h:15 · class · final · bases public ICoreDecoratedWindow · pImpl · 10 declaration(s)

class ICoreLibraryNavigator final : public ICoreDecoratedWindow {
public:
    explicit ICoreLibraryNavigator();

    void assembleBlocksHierarchy();

    static ICoreWidget* createGrandFamilyPanel(const std::string &grandFamilyName, const std::map<std::string, std::vector<std::string>> &grandFamily);

    static ICoreCollapsableWidget* createFamilyCollapsableStack(const std::string &grandFamilyName, const std::string &familyName,
                                                 const std::vector<std::string> &children);

    // The ready-made subsystems (ICoreTemplateLibrary), as their own category
    // beside the block families. They are dragged onto a canvas exactly like a
    // block, so this is where a user looks for them -- a template is a thing you
    // reach for while building, which is what the library IS.
    //
    // Bundle templates are left out: those are whole projects, and belong to the
    // New Project form rather than to a palette you drop onto a diagram.
    ICoreWidget* createTemplatesPanel();

    // The user's own blocks (ICoreUserBlockLibrary, USER_BLOCK_WIZARD.md §8):
    // the My Blocks category, one collapsable stack per family. Unlike every
    // other page this one REBUILDS live — the library fires its changed signal
    // on import/save/delete and the content is rebuilt from a fresh scan, so a
    // block imported with the app open appears without a restart.
    ICoreWidget* createMyBlocksPanel();
    void rebuildMyBlocksContent();

    // Toggle the navigator to the My Blocks page — the left panel's Block
    // Wizard button lands here (board row W3.4).
    void showMyBlocksPage() const;

    // Single search bar spanning every category: matches are gathered from the
    // whole library into one result page, no matter which category is toggled.
    void applyBlockFilter(const ICoreString &rawQuery);

    ~ICoreLibraryNavigator() override;

protected:
    // A press on one of the category toggle buttons, which are registered with
    // watchPointerPressesOf in the constructor.
    void watchedPointerPressed(ICoreNativeWidget* watched) override;
private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreLibraryNavigatorCard.h#

src/ICoreSDK/ICoreStudio/StudioObjects/Panels/LibraryNavigator/ICoreLibraryNavigatorCard.h

ICoreLibraryNavigatorCard#

ICoreLibraryNavigatorCard.h:29 · class · final · bases public ICoreWidget · pImpl · 8 declaration(s)

The floating card the library navigator shows while the pointer rests on a block entry: the block type's description (ICoreBlockFactory's HTML, the same text the config dialog's info panel renders)...

class ICoreLibraryNavigatorCard final : public ICoreWidget {
public:
    // The shared instance, created on first use. Parentless by design: it is a
    // top-level window whose lifetime is the application's, and giving it the
    // hovered entry as a parent would destroy it with the navigator page that
    // entry lives on.
    static ICoreLibraryNavigatorCard& instance();

    // Show the card for a block type, anchored beside `anchor` (the hovered
    // entry). A type with no registered description hides the card instead of
    // showing an empty one. Re-showing for the type already displayed just
    // cancels a pending hide, so crossing between an entry and its own card
    // never flickers.
    //
    // The first card of a hover sequence appears only after a dwell delay, so
    // the pointer can cross the list without dealing a card to every entry it
    // passes. Once a card IS on screen the delay is spent: moving to the next
    // entry swaps the description immediately, rather than leaving the previous
    // block's text under a pointer that has already moved on.
    void showFor(const std::string& blockType, ICoreWidget* anchor);

    // The same card for something that is not a block type — a template entry,
    // whose description is its own title and summary rather than anything the
    // block factory knows about. `key` is only an identity: it decides whether a
    // re-show is the same card (keep it exactly as it is) or a different one
    // (swap the text), so it need only be unique across whatever uses this.
    // Empty html hides the card, exactly as an undescribed block type does.
    void showHtml(const std::string& key, const ICoreString& html, ICoreWidget* anchor);

    // Hide after a short grace period, so the pointer can travel from the entry
    // onto the card. Entering the card cancels it.
    void requestHide();

    // Hide now, with no grace period: for a click, a drag, or the navigator
    // going away, where the card must not linger.
    void hideNow();

protected:
    void paintContent(ICorePainter& painter) override;
    void pointerEntered() override;
    void pointerLeft() override;
private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreLibraryNavigatorEntry.h#

src/ICoreSDK/ICoreStudio/StudioObjects/Panels/LibraryNavigator/ICoreLibraryNavigatorEntry.h

The description card is a top-level window, so it does not disappear with the widget it was opened from. An entry that goes away -- filtered out by the search, on a category page being switched, or destroyed with the navigator -- has to take its card down itself.

ICoreLibraryNavigatorEntry#

ICoreLibraryNavigatorEntry.h:10 · class · final · bases public ICoreWidget · pImpl · 8 declaration(s)

class ICoreLibraryNavigatorEntry final : public ICoreWidget {
public:
    explicit ICoreLibraryNavigatorEntry(ICoreWidget* parent,
                const std::string& grandFamilyName,
                const std::string& familyName,
                const std::string& childName);

    ~ICoreLibraryNavigatorEntry() override;

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

    // The description card is a top-level window, so it does not disappear with
    // the widget it was opened from. An entry that goes away -- filtered out by
    // the search, on a category page being switched, or destroyed with the
    // navigator -- has to take its card down itself.
    void hidden() override;
private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreLibraryTemplateEntry.h#

src/ICoreSDK/ICoreStudio/StudioObjects/Panels/LibraryNavigator/ICoreLibraryTemplateEntry.h

ICoreLibraryTemplateEntry#

ICoreLibraryTemplateEntry.h:22 · class · final · bases public ICoreWidget · pImpl · 9 declaration(s)

A subsystem template in the library navigator, sitting in the same grid as the block entries and dragged onto a canvas the same way -- the difference being what lands: a block entry drops one block...

class ICoreLibraryTemplateEntry final : public ICoreWidget {
public:
    ICoreLibraryTemplateEntry(ICoreWidget* parent, ICoreTemplateLibrary::Entry entry);

    ~ICoreLibraryTemplateEntry() override;

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

    // The card is a top-level window and outlives this widget, so an entry that
    // goes away -- filtered out by the search, or destroyed with the navigator --
    // has to take its card down itself.
    void hidden() override;
private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreLibraryUserBlockEntry.h#

src/ICoreSDK/ICoreStudio/StudioObjects/Panels/LibraryNavigator/ICoreLibraryUserBlockEntry.h

ICoreLibraryUserBlockEntry#

ICoreLibraryUserBlockEntry.h:26 · class · final · bases public ICoreWidget · pImpl · 11 declaration(s)

One user block (a .iblock definition) as a library-navigator tile — the third tile kind beside ICoreLibraryNavigatorEntry (a compiled block type) and ICoreLibraryTemplateEntry (a ready-made subsyst...

class ICoreLibraryUserBlockEntry final : public ICoreWidget {
public:
    explicit ICoreLibraryUserBlockEntry(ICoreWidget* parent, ICoreUserBlockDefinition definition);
    ~ICoreLibraryUserBlockEntry() override;

    // "my blocks <family> <name> <summary>", lower case — what the navigator's
    // search filter matches against.
    ICoreString searchKey() const;

protected:
    void paintContent(ICorePainter& painter) override;
    void pointerEntered() override;
    void pointerLeft() override;
    bool mousePressed(const ICoreMouseEvent& event) override;
    bool mouseMoved(const ICoreMouseEvent& event) override;
    bool mouseReleased(const ICoreMouseEvent& event) override;
    bool contextMenuRequested(const ICorePoint& globalPos) override;

    // Same contract as the other two tile kinds: the description card is a
    // top-level window and outlives this entry, so every teardown path has to
    // take it down.
    void hidden() override;
private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreTemplatePreview.h#

src/ICoreSDK/ICoreStudio/StudioObjects/Panels/LibraryNavigator/ICoreTemplatePreview.h

ICoreTemplatePreview#

ICoreTemplatePreview.h:26 · class · nested Palette · 0 declaration(s)

A small picture of what a template contains, drawn from the template's own recipe text.

class ICoreTemplatePreview {
public:
    struct Palette {
        ICoreColor background;
        ICoreColor blockFill;
        ICoreColor blockBorder;
        ICoreColor link;
    };

    // Renders `recipeText` into a pixmap of `size` (device-pixel-ratio aware).
    // A recipe with nothing drawable in it -- no blocks, or none with a position
    // -- returns a null pixmap, which callers should treat as "show the fallback
    // icon" rather than as an error: an empty template is a legitimate thing to
    // have saved.
    static ICorePixmap render(const ICoreString& recipeText, const ICoreSizeF& size,
                              const Palette& palette, double devicePixelRatio = 1.0);
};
};