API — ICoreBlocks/ICoreStudio/StudioManager

The public contract of 10 header(s) under src/ICoreBlocks/ICoreStudio/StudioManager — 10 class/struct definition(s), 214 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICoreStudioGarbageCollection.h#

src/ICoreBlocks/ICoreStudio/StudioManager/GarbageManager/ICoreStudioGarbageCollection.h

ICoreStudioGarbageCollection#

ICoreStudioGarbageCollection.h:45 · class · 39 declaration(s)

class ICoreStudioGarbageCollection {
public:

    // =========================================================
    // Garbage Collection
    // =========================================================
    static void collectGarbage_TreeNode(ICoreSubsystemTreeNode *nodeToCollect);
    static void collectGarbage_Block(ICoreBlock *blockToCollect);
    static void collectGarbage_Port(ICorePort *portToCollect);
    static void collectGarbage_PortUI(ICorePortView *portUIToCollect);
    static void collectGarbage_BlockUI(ICoreBlockView *blockUI);
    static void collectGarbage_BlockConfigurator(ICoreBlockConfigurator *configuratorToCollect);
    static void collectGarbage_BlockConfigVariable(ICoreBlockConfigVariable *configVariable);
    static void collectGarbage_BlockConfigUI(ICoreBlockConfigView* configUIToCollect);
    static void collectGarbage_BlockConfigUI_AddInputPortButton(ICoreBlockConfigViewAddInputPortButton* buttonToCollect);
    static void collectGarbage_BlockConfigUI_AddOutputPortButton(ICoreBlockConfigViewAddOutputPortButton* buttonToCollect);
    static void collectGarbage_BlockConfigUI_DeleteInputPortButton(ICoreBlockConfigViewDeleteInputPortButton* buttonToCollect);
    static void collectGarbage_BlockConfigUI_DeleteOutputPortButton(ICoreBlockConfigViewDeleteOutputPortButton* buttonToCollect);
    static void collectGarbage_BlockConfigDialog(ICoreBlockConfigView_ConfigDialog *configDialogToCollect);
    static void collectGarbage_BlockConfigDialogContentPaneEntry(ICoreBlockConfigDialogContentPaneEntry *entryToCollect);
    static void collectGarbage_BlockDescDialog(ICoreBlockConfigView_DescriptionDialog *descDialogToCollect);
    static void collectGarbage_BlockSubsystemGate(ICoreBlockSubsystemGate *gateToCollect);
    static void collectGarbage_Link(ICoreLink *linkToCollect);
    static void collectGarbage_LinkBranch(ICoreLinkBranch *branchToCollect);
    static void collectGarbage_LinkBranchSegment(ICoreLinkBranchSegment *segToCollect);
    static void collectGarbage_CanvasArea(ICoreCanvasArea *areaToCollect);
    static void collectGarbage_CanvasAreaUI(ICoreCanvasAreaView *areaUIToCollect);
    static void collectGarbage_TextBox(ICoreCanvasTextBox *textBoxToCollect);
    static void collectGarbage_TextBoxUI(ICoreCanvasTextBoxView *boxUIToCollect);
    static void collectGarbage_Image(ICoreImage *imageToCollect);
    static void collectGarbage_ImageUI(ICoreImageView *imageToCollect);
    static void collectGarbage_CanvasOriginAnchor(ICoreCanvasOriginAnchor *anchorToCollect);
    static void collectGarbage_Chart(ICoreChart* chart);
    static void collectGarbage_Tab(ICoreTab *tabToCollect);
    static void collectGarbage_TabHeader(ICoreTabHeader *tabHeaderToCollect);
    static void collectGarbage_Canvas(ICoreCanvas *canvasToCollect);
    static void collectGarbage_CanvasSelectionModel(ICoreCanvasSelectionModel* selectionModelToCollect);
    static void collectGarbage_StudioSurfaceNavBarQuickReachButton(ICoreNavBarQuickReachButton *buttonToCollect);
    // The four Essentials graphics collectors moved down to
    // ICoreEssentials/UI/Graphics/ICoreGraphicsRecycler (ESSENTIALS_INDEPENDENCE D5).
    static void collectGarbage_MessageBox(ICoreNotificationCenterMessageBox* boxToCollect);
    static void collectGarbage_TreeViewModel(ICoreTreeViewModel *modelToCollect);
    static void collectGarbage_EditorState(ICoreProjectState *stateToCollect);
    static void collectGarbage_ObjectState(ICoreCanvasObjectState *stateToCollect);
    static void collectGarbage_PortImage(ICorePortImage *imageToCollect);
    static void collectGarbage_LinkBranchImage(ICoreLinkBranchImage *imageToCollect);
    static void collectGarbage_LinkImage(ICoreLinkImage *imageToCollect);

};
};

ICoreStudioGarbageRecycling.h#

src/ICoreBlocks/ICoreStudio/StudioManager/GarbageManager/ICoreStudioGarbageRecycling.h

ICoreStudioGarbageRecycling#

ICoreStudioGarbageRecycling.h:89 · class · 77 declaration(s)

THE POOL OWNS EVERY OBJECT IT HANDS OUT, AND NEVER FREES ONE.

class ICoreStudioGarbageRecycling {
public:

    // -------------- ICoreSubsystemTreeNode ------------------
    static void recycle_TreeNode(ICoreSubsystemTreeNode* treeNode);
    static ICoreSubsystemTreeNode* requestRecycled_TreeNode(ICoreSubsystemTreeNode* parent = nullptr, const std::string& initName = "~auto");

    // -------------- Block ------------------
    // ---- Block ----
    static void recycle_Block(ICoreBlock* block);
    static ICoreBlock* requestRecycled_Block(ICoreSubsystemTreeNode* parent, std::string type);

    // ---- BlockUI ----
    static void recycle_BlockUI(ICoreBlockView* blockUI);
    static ICoreBlockView* requestRecycled_BlockUI(ICoreGraphicsObject *parent = nullptr, ICoreBlock* parentBlock = nullptr);

    // ---- Config ----
    static void recycle_BlockConfigurator(ICoreBlockConfigurator* configurator);
    static void recycle_BlockConfigVariable(ICoreBlockConfigVariable* configVariable);
    static void recycle_BlockConfigUI(ICoreBlockConfigView* configUI);
    static void recycle_BlockConfigUI_AddInputPortButton(ICoreBlockConfigViewAddInputPortButton* buttonToCollect);
    static void recycle_BlockConfigUI_AddOutputPortButton(ICoreBlockConfigViewAddOutputPortButton* buttonToCollect);
    static void recycle_BlockConfigUI_DeleteInputPortButton(ICoreBlockConfigViewDeleteInputPortButton* buttonToCollect);
    static void recycle_BlockConfigUI_DeleteOutputPortButton(ICoreBlockConfigViewDeleteOutputPortButton* buttonToCollect);
    static void recycle_BlockConfigDialog(ICoreBlockConfigView_ConfigDialog* configDialog);
    static void recycle_BlockConfigDialogContentPaneEntry(ICoreBlockConfigDialogContentPaneEntry* entryToCollect);
    static void recycle_BlockDescDialog(ICoreBlockConfigView_DescriptionDialog* descDialog);
    static ICoreBlockConfigurator* requestRecycled_BlockConfigurator(ICoreBlock* parentBlock);
    static ICoreBlockConfigVariable* requestRecycled_BlockConfigVariable(const std::string& name, const std::string& value, const bool& isPrivate = false);
    static ICoreBlockConfigView* requestRecycled_BlockConfigUI(ICoreCanvas* parent, ICoreBlockConfigurator* parentBlockConfigurator);
    static ICoreBlockConfigViewAddInputPortButton* requestRecycled_AddInputPortButton(ICoreBlockConfigView* graphicsParent, ICoreBlockConfigurator* parentBlockConfigurator);
    static ICoreBlockConfigViewAddOutputPortButton* requestRecycled_AddOutputPortButton(ICoreBlockConfigView* graphicsParent, ICoreBlockConfigurator* parentBlockConfigurator);
    static ICoreBlockConfigViewDeleteInputPortButton* requestRecycled_DeleteInputPortButton(ICoreBlockConfigView* graphicsParent, ICoreBlockConfigurator* parentBlockConfigurator);
    static ICoreBlockConfigViewDeleteOutputPortButton* requestRecycled_DeleteOutputPortButton(ICoreBlockConfigView* graphicsParent, ICoreBlockConfigurator* parentBlockConfigurator);
    static ICoreBlockConfigView_ConfigDialog* requestRecycled_BlockConfigDialog(ICoreCanvas* parentCanvas, ICoreBlockConfigurator* parentBlockConfigurator, ICoreBlockConfigView* grandParentConfigUI);
    static ICoreBlockConfigDialogContentPaneEntry* requestRecycled_BlockConfigDialogContentPaneEntry(ICoreBlockConfigDialogContentPane* parentDialogContentPane, ICoreBlockConfigVariable* variable);
    static ICoreBlockConfigView_DescriptionDialog* requestRecycled_BlockDescDialog(ICoreCanvas* parentCanvas, ICoreBlockConfigurator* parentBlockConfigurator);

    // ---- Block subsystem gate ----
    static void recycle_BlockSubsystemGate(ICoreBlockSubsystemGate* gate);
    static ICoreBlockSubsystemGate* requestRecycled_BlockSubsystemGate(ICoreBlock* parentBlock);

    // ---- Port ----
    static void recycle_Port(ICorePort* port);
    static void recycle_PortUI(ICorePortView* portUI);
    static ICorePort* requestRecycled_Port(ICoreBlock* parentBlock, const std::string &type, const std::string &initialPortDescription,
                const bool isOutputPort, const std::string& preferredFacing);
    static ICorePortView* requestRecycled_PortUI(ICoreBlockViewFrame* parent = nullptr, ICorePort* parentPort = nullptr, ICoreBlockView* grandParentBlockUI = nullptr);

    // -------------- Link ------------------
    static void recycle_Link(ICoreLink* link);
    static void recycle_LinkBranch(ICoreLinkBranch* branch);
    static void recycle_LinkBranchSegment(ICoreLinkBranchSegment* branchSeg);
    // static void recycle_LinkBranchHeadPane(ICoreLinkBranchHeadPane* headPane);
    // static void recycle_LinkBranchHead(ICoreLinkBranchHead* head);
    // static void recycle_LinkBranchTailPane(ICoreLinkBranchTailPane* tailPane);
    // static void recycle_LinkBranchTailCircle(ICoreLinkBranchTailCircle* tailCircle);
    // static void recycle_LinkBranchTail(ICoreLinkBranchTail* tail);
    // static void recycle_LinkBranchSegmentMover(ICoreLinkBranchSegmentMover* mover);
    static ICoreLink* requestRecycled_Link(ICoreSubsystemTreeNode* parent, std::string type);
    static ICoreLinkBranch* requestRecycled_LinkBranch(ICoreLink* parentLink = nullptr);
    static ICoreLinkBranchSegment* requestRecycled_LinkBranchSegment(ICoreGraphicsObject *parent = nullptr, ICoreLinkBranch* parentLinkBranch = nullptr, ICoreLinkBranchSegmentMover* linkSegmentMover = nullptr);
    // static ICoreLinkBranchHeadPane* requestRecycled_LinkBranchHeadPane(ICoreGraphicsObject *parent = nullptr, ICoreLinkBranch *parentLinkBranch = nullptr);
    // static ICoreLinkBranchHead* requestRecycled_LinkBranchHead(ICoreLinkBranch* parentLinkBranch = nullptr);
    // static ICoreLinkBranchTailPane* requestRecycled_LinkBranchTailPane(ICoreGraphicsObject *parent, ICoreLinkBranch *parentLinkBranch);
    // static ICoreLinkBranchTailCircle* requestRecycled_LinkBranchTailCircle(ICoreGraphicsObject *parent = nullptr, ICoreLinkBranch* parentLinkBranch = nullptr);
    // static ICoreLinkBranchTail* requestRecycled_LinkBranchTail(ICoreLinkBranch* parentLinkBranch = nullptr);
    // static ICoreLinkBranchSegmentMover* requestRecycled_LinkBranchSegmentMover(ICoreLinkBranch* parent);

    // -------------- Canvas Area ------------------
    static void recycle_CanvasAreaUI(ICoreCanvasAreaView* areaUI);
    static void recycle_CanvasArea(ICoreCanvasArea* area);
    static ICoreCanvasAreaView* requestRecycled_CanvasAreaUI(ICoreGraphicsObject* parent, ICoreCanvasArea* parentCanvasArea);
    static ICoreCanvasArea* requestRecycled_CanvasArea(ICoreSubsystemTreeNode* parent);

    // -------------- TextBox ------------------
    static void recycle_TextBoxUI(ICoreCanvasTextBoxView* noteUI);
    static void recycle_TextBox(ICoreCanvasTextBox* note);
    static ICoreCanvasTextBoxView* requestRecycled_TextBoxUI(ICoreGraphicsObject* parent = nullptr, ICoreCanvasTextBox* parentTextBox = nullptr);
    static ICoreCanvasTextBox* requestRecycled_TextBox(ICoreSubsystemTreeNode* parentTreeNode);

    // -------------- Image ------------------
    static void recycle_ImageUI(ICoreImageView* imageUI);
    static void recycle_Image(ICoreImage* image);
    static ICoreImageView* requestRecycled_ImageUI(ICoreGraphicsObject* parent = nullptr, ICoreImage* parentImage = nullptr);
    static ICoreImage* requestRecycled_Image(ICoreSubsystemTreeNode* parent);

    // -------------- Origin Anchor ------------------
    static void recycle_OriginAnchor(ICoreCanvasOriginAnchor* anchor);
    static ICoreCanvasOriginAnchor* requestRecycled_OriginAnchor(ICoreSubsystemTreeNode* parentTreeNode);

    // -------------- Charts ------------------
    static void recycle_Chart(ICoreChart* chart);
    static ICoreChart* requestRecycled_Chart(ICoreBlock *parentBlock);

    // -------------- Tab -----------------
    static void recycle_Tab(ICoreTab* tab);
    static void recycle_TabHeader(ICoreTabHeader* tabHeader);
    static ICoreTab* requestRecycled_Tab(ICoreStudioSurface* parent);
    static ICoreTabHeader* requestRecycled_TabHeader(ICoreTab* associatedTab, ICoreWidget* parent = nullptr);

    // -------------- Canvas ------------------
    static void recycle_Canvas(ICoreCanvas* canvas);
    static void recycle_CanvasSelectionModel(ICoreCanvasSelectionModel* model);
    static ICoreCanvas* requestRecycled_Canvas(ICoreTab* parentTab);
    static ICoreCanvasSelectionModel* requestRecycled_CanvasSelectionModel();

    // -------------- ICoreNavBarQuickReachButton -----------------
    static void recycle_StudioSurfaceNavBarQuickReachButton(ICoreNavBarQuickReachButton* buttonToCollect);
    static ICoreNavBarQuickReachButton* requestRecycled_StudioSurfaceNavBarQuickReachButton(ICoreWidget *parent, ICoreStudioSurface* parentStudioSurface, const std::string& path);

    // The four Essentials graphics pools that sat here -- TableEntryRow,
    // ComboBox_ComboOption, BoxedText (with its P2.10b-3b narrowing note) and
    // TableTitleRowSplitter -- moved down whole to
    // ICoreEssentials/UI/Graphics/ICoreGraphicsRecycler
    // (ESSENTIALS_INDEPENDENCE D5): every caller was an Essentials file, and
    // the pools were the table widgets' own allocation strategy. The MessageBox
    // request below keeps its historical (copy-pasted) name; it is unrelated
    // to the splitter pool that left.

    // -------------- MessageBox -----------------
    static void recycle_MessageBox(ICoreNotificationCenterMessageBox* box);
    static ICoreNotificationCenterMessageBox* requestRecycled_GraphicsTableTitleRowSplitter(ICoreNativeWidget* parent = nullptr,
            const std::string& title = "Message", const std::string& message = "");

    // -------------- ICoreTreeViewModel -----------------
    static void recycle_TreeViewModel(ICoreTreeViewModel* model);
    // Narrowed from ICoreAnyWidget* with the model's conversion: the parent is
    // used purely as an object parent, and ICoreTreeViewModel resolves it
    // through icoreNativeObjectOfWidget() internally.
    static ICoreTreeViewModel* requestRecycled_TreeViewModel(ICoreNativeWidget* parent = nullptr);

    // -------------- State Machine -----------------
    static void recycle_EditorState(ICoreProjectState* state);
    static void recycle_ObjectState(ICoreCanvasObjectState* state);
    static ICoreProjectState* requestRecycled_EditorState();
    static ICoreCanvasObjectState* requestRecycled_ObjectState(const std::string& classID, const std::string& objectType, const std::string& path);

    // -------------- ICorePortImage -----------------
    static void recycle_PortImage(ICorePortImage* imageToCollect);
    static void recycle_LinkBranchImage(ICoreLinkBranchImage* imageToCollect);
    static void recycle_LinkImage(ICoreLinkImage* imageToCollect);
    static ICorePortImage* requestRecycled_PortImage(ICorePort* originalPort);
    static ICoreLinkBranchImage* requestRecycled_LinkBranchImage(ICoreLinkBranch *originalBranch);
    static ICoreLinkImage* requestRecycled_LinkImage(ICoreLink* originalLink);

    // -------------- Audit -----------------
    // What the link, branch, segment and port pools (and the three migration
    // image pools) hold right now, checked against the pool contract: every
    // entry is dead, none is pooled twice, and none still points into the live
    // diagram. One sentence per violation; empty means the pools are clean.
    // Read-only, and not gated on ICORE_DIRTY_RECYCLE_GUARDS -- it is what
    // ICoreDiagramIntegrity::auditSession() reports the pools with.
    static std::vector<std::string> auditLinkPools();

// The 42 recycling pools that used to be declared here are private static data,
    // so they live in the .cpp's anonymous namespace instead -- this class is
    // all-static and has no Impl to hold them. See there for the per-type sections.
};
};

ICoreStudioEditorHost.h#

src/ICoreBlocks/ICoreStudio/StudioManager/Host/ICoreStudioEditorHost.h

ICoreStudioEditorHost#

ICoreStudioEditorHost.h:24 · class · 1 declaration(s)

ICoreStudioEditorHost -- the studio side of ICoreEditorHost.

class ICoreStudioEditorHost {
public:
    static void installEditorHostServices();
};
};

ICoreDiagramIntegrity.h#

src/ICoreBlocks/ICoreStudio/StudioManager/Integrity/ICoreDiagramIntegrity.h

ICoreDiagramIntegrity#

ICoreDiagramIntegrity.h:21 · class · 4 declaration(s)

A read-only audit of a diagram's wiring.

class ICoreDiagramIntegrity {
public:
    // `treeNode` and every subsystem below it.
    static std::vector<std::string> auditTree(const ICoreSubsystemTreeNode* treeNode);

    // `treeNode` alone: its blocks' ports, its links, and the canvas it is on.
    static std::vector<std::string> auditLevel(const ICoreSubsystemTreeNode* treeNode);

    // The whole session: every tree node under the registry's root -- Home,
    // Temp and Trash included -- plus the link, branch, segment, port
    // and migration-image pools (ICoreStudioGarbageRecycling::auditLinkPools).
    static std::vector<std::string> auditSession();

    // True for a sentence about WHERE a wire is drawn (a wire end away from its
    // port, a tee attached to nothing) rather than about what the model says.
    // Those sentences start with "[geometry] ".
    static bool isGeometryIssue(const std::string& issue);

    // Runs auditLevel() and logs every model violation through ICoreLogger,
    // prefixed with "[Diagram integrity] after <afterWhat>". Geometry sentences
    // are left out of the log. Returns how many it logged. This is how an edit
    // checks its own result in the field.
    static std::size_t logStructuralViolations(const ICoreSubsystemTreeNode* treeNode,
                                               const std::string& afterWhat);
};
};

ICoreRecipeStudioBridge.h#

src/ICoreBlocks/ICoreStudio/StudioManager/Recipe/ICoreRecipeStudioBridge.h

ICoreRecipeStudioBridge#

ICoreRecipeStudioBridge.h:43 · class · nested Colour, CanvasPos · 9 declaration(s)

The studio-side half of the recipe machinery.

class ICoreRecipeStudioBridge {
public:
    // ---- colour ------------------------------------------------------------

    // An RGBA colour in the 0-255 channel form the recipe language speaks.
    // Defaults to opaque black, matching ICoreCanvasAreaView's own default.
    struct Colour {
        int red   = 0;
        int green = 0;
        int blue  = 0;
        int alpha = 255;
    };

    // Parse a colour name ("red") or hex string ("#rrggbb", "#aarrggbb") into
    // `out`. Returns false and leaves `out` untouched if the text names no
    // known colour. Quotes must already be stripped by the caller.
    static bool parseColour(const ICoreString& text, Colour& out);

    // "#rrggbb" -- alpha is dropped. The short form the info sheets print.
    static ICoreString formatColourRgb(const Colour& colour);

    // "#rrggbb" when fully opaque, "#aarrggbb" otherwise, so a colour with
    // transparency round-trips through the printed form.
    static ICoreString formatColourPreservingAlpha(const Colour& colour);

    // Null-safe: an area with no UI reads back as the default Colour.
    static Colour areaColour(const ICoreCanvasAreaView* ui);
    static void   setAreaColour(ICoreCanvasAreaView* ui, const Colour& colour);

    // ---- geometry ----------------------------------------------------------

    // Integer canvas coordinates relative to the subsystem's origin anchor,
    // +y DOWN (the screen's sense -- callers that print in the recipe
    // language's +y-up convention flip the sign themselves, as they did before
    // this existed).
    // Null UI reads back as (0, 0), which is what the call sites relied on.
    struct CanvasPos {
        int x = 0;
        int y = 0;
    };
    static CanvasPos posRelativeToCanvasOrigin(const ICoreCanvasAreaView* ui);
    static CanvasPos posRelativeToCanvasOrigin(const ICoreImageView* ui);
    static CanvasPos posRelativeToCanvasOrigin(const ICoreCanvasTextBoxView* ui);

    // Replace a branch's corner path. Coordinates are relative to the canvas
    // origin anchor and already in the screen's +y-down sense. No-op on a null branch
    // or a path shorter than two corners -- the caller is expected to have
    // rejected those loudly, since the sink below ignores them silently.
    static void setBranchCornersRelativeToCanvasOrigin(ICoreLinkBranch* branch,
                                                       const std::vector<ICorePoint>& corners);

    // ---- chart -------------------------------------------------------------

    // Decode a serialized-font blob (ICoreStudioStaticCommands::serializeFont's
    // key=value map) and apply it to the chart's x or y axis. No-op on a null
    // chart.
    static void setChartAxisFont(ICoreChart* chart, bool isX,
                                 const std::unordered_map<std::string, std::string>& serializedFont);

    // ---- image -------------------------------------------------------------

    // True when the file at `path` is an image this build can actually decode.
    // The real loader ignores unreadable files silently, so callers probe with
    // this first in order to report a real error.
    static bool isDecodableImage(const ICoreString& path);
};
};

ICoreStudioSerialization.h#

src/ICoreBlocks/ICoreStudio/StudioManager/Serialization/ICoreStudioSerialization.h

Writes out a debounced autosave that has not fired yet. Called when the app is closing: the pending write is the user's last edits, and letting the timer die with the process would drop them. A no-op when autosave is synchronous (the default) or nothing is pending.

ICoreStudioSerialization#

ICoreStudioSerialization.h:8 · class · 11 declaration(s)

class ICoreStudioSerialization {
public:

    static void triggerAutoSave();

    // Writes out a debounced autosave that has not fired yet. Called when the
    // app is closing: the pending write is the user's last edits, and letting
    // the timer die with the process would drop them. A no-op when autosave is
    // synchronous (the default) or nothing is pending.
    static void flushPendingAutoSave();

    // ------------- Project Save/Load --------------
    // The .iproj file is now plain recipe text (see ICoreRecipeSerializer /
    // ICoreRecipeInterpreter), one statement per line - ICoreActiveProjectFolder's
    // save/load plumbing (temp file, atomic rename) is unchanged; only what
    // text goes through it changed.
    static void saveSerializedProjectToDisk();
    static void loadProjectFromDisk();

    // Writes only the project's sidecars (solver.ini, exportTargets.ini,
    // projectPreferences.ini), leaving the .iproj alone.
    //
    // For the settings that are project data but are NOT diagram edits: changing
    // one logs no action, so it never starts the autosave timer, and without this
    // it would sit unwritten until the app closed and flushPendingAutoSave()
    // caught it. A no-op when no project is open, and it does NOT clear the
    // failed-load guard -- it has written nothing over the .iproj to justify that.
    static void saveProjectSidecarsToDisk();

    // Writes the model ON SCREEN and its three sidecars into `folder` as a
    // project of its own -- <folder>/<folder name>.iproj, solver.ini,
    // exportTargets.ini, projectPreferences.ini -- leaving the open project's
    // files and every autosave gate alone. The copy a coding agent's change is
    // tried on in another process (ICoreAgentSandbox, AGENT_BRIDGE.md AB.28).
    // A referenced subsystem is written as its path, as a save writes it, so
    // its file must be in the folder already. False when a file was not written.
    static bool writeSnapshotTo(const std::filesystem::path& folder);

    // Brings the editor to an empty project and writes it out, so the folder the
    // two project statics currently point at ends up holding a real <name>.iproj.
    //
    // This is deliberately NOT loadProjectFromDisk() on a folder that has no
    // .iproj yet: that path reports a failed read and a missing Images folder as
    // errors, which is exactly what a brand-new project legitimately looks like.
    // Same wipe-and-replay primitive, no disk read, no error noise.
    //
    // Callers must have pointed ICoreDocumentsFolder / ICoreActiveProjectFolder
    // at the new project first -- that is what says where this writes.
    static void startNewEmptyProject();

    // True between a load that could not be replayed and the next successful
    // load / new project / explicit save. See the flag below.
    static bool didLastProjectLoadFail();

    // The internal autosave kill switch, for code that must not let a write
    // happen underneath it while it moves something autosave depends on. The
    // regression sandbox holds it across repointing the documents folder, and
    // puts it back to whatever it found. Separate from the user's Settings
    // preference (ICoreUserPreferences::isAutosaveEnabled), which this does not
    // touch: both have to be on for a write to happen.
    static void setAutosaveSuspended(bool suspended);
    static bool isAutosaveSuspended();

    // TEST SUPPORT ONLY -- ICoreRegressionSandbox. The regression suite has
    // cases that deliberately fail a load, which sets the guard; the sandbox has
    // to hand the session back the value it started with rather than whatever
    // the last case left. Nothing in the app should call this: every real way
    // the flag changes is a load, a save or a new project, and short-circuiting
    // that is how autosave would come back on over a project it must stay off.
    static void restoreProjectLoadFailedState(bool failed);

    // This class is all-static and holds no instance, so it has no Impl: the
    // header surface rule is satisfied by the private statics and helpers
    // living in the .cpp's anonymous namespace instead. See there for the
    // project-sidecar contract, the autosave kill switch and the failed-load
    // guard that used to be declared here.
};
};

ICoreModelEditFreeze.h#

src/ICoreBlocks/ICoreStudio/StudioManager/StateMachine/ICoreModelEditFreeze.h

ICoreModelEditFreeze#

ICoreModelEditFreeze.h:22 · class · 2 declaration(s)

Owner ruling D3 (per-subsystem undo, 2026-09-23): the model may be edited while a SIMULATION runs -- that is what an infinite run is for -- but NOT while code is being exported, parsed or verified.

class ICoreModelEditFreeze {
public:
    static constexpr const char* kTitle = "Code Export Running";
    static constexpr const char* kMessage = "Can't edit the model while code export is running.";

    static bool isFrozen();

    // True -- and the error shown -- when frozen; the caller must then not edit.
    // The notification is throttled (one per second) so a burst of refused input
    // does not stack a pile of identical notices.
    static bool refuseEdit();
};
};

ICoreStudioStateMachine.h#

src/ICoreBlocks/ICoreStudio/StudioManager/StateMachine/ICoreStudioStateMachine.h

ICoreStudioStateMachine#

ICoreStudioStateMachine.h:21 · class · nested NodeHistoryResult · 39 declaration(s)

class ICoreStudioStateMachine {
public:

    static long initializeStateMachine();

    // =========================================================
    // ClassID Manager
    // =========================================================
    static std::string requestClassID_Block(ICoreBlock* newlyCreatedBlock);
    static std::string requestClassID_VariablesSpace(ICoreVariablesSpace* newlyCreatedVariablesSpace);
    static std::string requestClassID_Link(ICoreLink* newlyCreatedLink);
    static std::string requestClassID_CanvasArea(ICoreCanvasArea* newlyCreatedCanvasAreas);
    static std::string requestClassID_TextBox(ICoreCanvasTextBox* newlyCreatedTextBox);
    static std::string requestClassID_Image(ICoreImage* newlyCreatedImage);

    static ICoreBlock* getBlockFromClassID(const std::string& classID);
    static ICoreVariablesSpace* getVariableSpaceFromClassID(const std::string& classID);
    static ICoreLink* getLinkFromClassID(const std::string& classID);
    static ICoreCanvasArea* getCanvasAreaFromClassID(const std::string& classID);
    static ICoreCanvasTextBox* getTextBoxFromClassID(const std::string& classID);
    static ICoreImage* getImageFromClassID(const std::string& classID);

    // ========
    // Other objects Cached memory
    // ===============================
    static std::string cacheNewPixmap(const ICorePixmap& pixmap);
    static ICorePixmap getCachedNewPixmap(const std::string &pixmapId);
    static void overwriteAllCachedPixmap(const std::unordered_map<std::string, ICorePixmap>& newPixmaps);

    // =========================================================
    // States Manager — recipe capture/replay (see ICoreRecipeSerializer /
    // ICoreRecipeInterpreter). Two captures, one replay primitive:
    //   * the WHOLE-project recipe (getCurrentRecipe) is what a save writes and
    //     what a project load replays;
    //   * one LOCAL text per subsystem (ICoreRecipeSerializer::serializeLocal) is
    //     what the per-subsystem undo/redo history stores.
    // Both are applied by wiping Home to empty and replaying: there is no
    // incremental in-place patching -- every undo/redo/load rebuilds the diagram.
    // The project-wide undo stack that preceded the per-subsystem one was removed
    // in H12 (2026-09-23).
    // =========================================================
    static void logNewAction(const std::string& action);
    // logNewAction(), but only when the diagram (the whole-project recipe) actually
    // differs from the current recipe; returns whether it logged. For compound
    // operations that can end up changing nothing (a refused reduction, a console
    // statement that only read something), so they never spend an undo step or
    // trip autosave for nothing.
    static bool logNewActionIfChanged(const std::string& action);
    // Notes that the diagram MAY have been edited by something that does not log
    // (a console / script recipe statement). Cheap: one comparison against the
    // current recipe runs on the next event-loop turn -- so a script of 10k
    // statements costs one capture, not 10k -- and before undo(), redo() and
    // getCurrentRecipe() (so every save), whichever comes first. A no-op while
    // logging is paused (replay, import).
    static void notePossibleUnloggedEdit();
    // What the user's Undo / Redo does -- Edit menu (Ctrl+Z, Ctrl+Shift+Z, Ctrl+Y),
    // the top bar's buttons and ICoreAPIs::undo/redo all end here. Since H9
    // (per-subsystem undo) they step the history of the subsystem the FOCUSED
    // canvas shows (Home when no canvas has focus, nothing on Trash/Temp),
    // through undoInNode()/redoInNode(); a D1 refusal is shown as a warning
    // notification naming the level that has the newer edits.
    static void undo();
    static void redo();
    // Wipes Home to empty and replays `recipe` onto it (used by applyLocalTexts,
    // i.e. every undo/redo, and by ICoreStudioSerialization::loadProjectFromDisk).
    // Public so ICoreStudioSerialization can drive a project load through the same
    // path as undo/redo.
    // `skipChartState`: when true, every line that configures a Scope block's
    // attached ICoreChart (chart(), xlabel/ylabel, setAxisFont, path(i),
    // applyStyle, ...) is left unevaluated - the chart keeps whatever default
    // state it gets from being recreated with its block. Nothing in the product
    // passes true since H12 removed the project-wide undo that did; undo/redo and
    // project load both restore charts in full.
    // `isUndoRedo`: when true (only from an undo/redo), ICoreStudioSurfaceRegistry's
    // tab cleanup (deleteAllTabsWithoutLoadedTreeNode / deleteAllTabsOutsideHomeTreeNode)
    // is paused for the duration of the wipe+replay, so neither runs. Project load passes
    // false (the default) so tabs are still cleaned up normally there.
    //
    // Returns false when replay gave up part-way -- a line this build's grammar
    // does not recognise, i.e. an older project format or a corrupted file. Home
    // is then whatever had been rebuilt before that line, which is usually
    // nothing. Callers that are about to write the result back to disk have to
    // check this: ICoreStudioSerialization::loadProjectFromDisk does.
    //
    // It leaves getCurrentRecipe() describing the diagram it just built (a fresh
    // capture), so a save straight after it writes what is on screen and the next
    // logNewAction() pushes this diagram, not the one before it, onto the history.
    // It logs no action of its own: history and autosave are the caller's call.
    static bool applyRecipeSnapshot(const std::string& recipe, bool skipChartState = false, bool isUndoRedo = false);

    // The lines the most recent applyRecipeSnapshot() could not apply, each as
    // "<line>: <why>", in file order -- a statement the interpreter refused (it
    // is skipped and the replay goes on) and the unrecognised line that stopped
    // it. Empty after a clean replay. What was only ever written to the log is
    // what a user or a coding agent needs in order to fix a project file it
    // edited by hand (the agent-bridge board, AB.17).
    static std::vector<std::string> lastReplayProblems();

    // Rebuilds Home from per-subsystem texts (ICoreRecipeSerializer::serializeLocal,
    // keyed by NodeId; H5). The map is composed into one script
    // and applied through applyRecipeSnapshot() -- the whole replay every project
    // load and every undo already takes, so the gate/face-port ordering a subsystem
    // needs is the one a saved project already gets. Then every rebuilt subsystem
    // adopts the NodeId of the node it replaces, by position in the pre-order walk
    // compose() emitted, so anything keyed by id (a per-subsystem history) still
    // resolves; a node elsewhere (Trash) that held one of those ids is re-issued a
    // fresh one. `globals` is ICoreRecipeSerializer::serializeGlobals() text.
    //
    // Returns false -- with the diagram as applyRecipeSnapshot() left it -- when the
    // map does not compose, the replay gave up part-way, or the rebuilt tree does not
    // have the shape compose() emitted (ids are then NOT adopted, and it is logged).
    static bool applyLocalTexts(const ICoreRecipeSerializer::LocalMap& map, const ICoreString& globals,
                                bool skipChartState = false, bool isUndoRedo = false);

    // =========================================================
    // Per-subsystem history -- H7/H8
    //
    // Recorded alongside the project-wide history on every logged action: each
    // subsystem's local text is compared with the one cached for it, and the
    // subsystems whose text changed (Home as well when a global variable did) form
    // one TRANSACTION, pushed on each of their undo stacks. An action that changes
    // two levels -- creating a subsystem, a gate port, deleting a subsystem -- is one
    // transaction on both.
    //
    // undoInNode(id) takes the top transaction of that subsystem's stack and puts
    // back the texts it replaced, through applyLocalTexts(). Owner ruling D1: if
    // another subsystem the transaction touched has had NEWER edits since, the
    // undo is REFUSED and `refusal` names that subsystem -- it never silently
    // changes a canvas the user is not looking at. Same for redo.
    //
    // A whole replay that is not one of these (project load, new project, the
    // project-wide undo()) rebuilds every node with new ids, so it drops every
    // per-subsystem history (H10).
    //
    // ⚠ Scope charts ARE restored by a per-subsystem undo (the project-wide
    // undo() skips them): their lines are part of the level's text, and resetting
    // them to defaults on every undo loses settings that no step ever recorded.
    struct NodeHistoryResult {
        bool applied = false;     // something was undone / redone
        std::string refusal;      // non-empty when refused under D1, or when it failed
    };
    static NodeHistoryResult undoInNode(std::uint64_t nodeId);
    static NodeHistoryResult redoInNode(std::uint64_t nodeId);
    static bool canUndoInNode(std::uint64_t nodeId);
    static bool canRedoInNode(std::uint64_t nodeId);

    // ---- What the Undo/Redo controls show (H15). The Edit menu's items read the
    // focused canvas's subsystem (the one undo()/redo() act on); each top bar reads
    // the subsystem ITS window shows. A disabled menu item also swallows its
    // shortcut, so these must never go stale: every step logged, undone or redone
    // and every history dropped fires onUndoAvailabilityChanged(), and so does
    // notifyUndoAvailabilityChanged(), which focus and navigation changes call.
    static bool canUndoFocused();
    static bool canRedoFocused();
    static ICoreSignal<>& onUndoAvailabilityChanged();
    static void notifyUndoAvailabilityChanged();
    static void clearStateMachineStates();
    static void pauseLoggingNewActions();
    static void resumeLoggingNewActions();
    // Whether logNewAction() would log right now. A compound operation that pauses
    // logging reads this first and resumes only if it was on, so it can be called
    // from inside another paused operation without switching logging back on
    // underneath its caller.
    static bool isLoggingNewActions();

    static void ungrabMouseFromAllObjects();

    // Settles a pending notePossibleUnloggedEdit() first, so a save never writes
    // a diagram older than the one on screen.
    static const std::string& getCurrentRecipe();

    // Read-only inventory of the live blocks / links the session currently holds,
    // for the pointer-inspector UI. Returned by value (snapshots) and already
    // filtered on isAlive(): a collected object stays registered while it waits in
    // its recycling pool, and is left out here. Objects in the internal staging
    // nodes (Temp / Trash) are alive and included, so this is not a
    // count of what is on the diagram -- count the recipe's statements for that.
    static std::vector<ICoreBlock*> getAllProjectBlocks();
    static std::vector<ICoreLink*> getAllProjectLinks();

// The static storage, the three recipe helpers and the logging switch that used
// to be declared here are private, and this class is all-static, so there is no
// Impl to hold them -- they live in the .cpp's anonymous namespace. The long
// notes on captureCurrentRecipe / replayRecipeText
// moved with them.
};
};

ICoreCanvasObjectState.h#

src/ICoreBlocks/ICoreStudio/StudioManager/StateMachine/Objects/ICoreCanvasObjectState.h

ICoreCanvasObjectState#

ICoreCanvasObjectState.h:6 · class · pImpl · 17 declaration(s)

class ICoreCanvasObjectState {
public:
    explicit ICoreCanvasObjectState(const std::string& classID, const std::string& objectType, const std::string& path);

    // Property management
    void addProperty(const std::string& key, const std::string& value);
    void addMapProperties(const std::unordered_map<std::string, std::string> &map);
    std::string getProperty(const std::string& key) const;
    void clearProperty(const std::string& key);
    void clearAllProperties();

    // Getters
    std::string getClassID() const;
    std::string getObjectType() const;
    std::string getPath() const;
    int getTreeNodeOrder() const;
    const std::unordered_map<std::string, std::string>& getState() const;

    // Print details
    void printDetails() const;

    void resetToInitialState(const std::string& classID, const std::string& objectType, const std::string& path);
    void kill();
    void setAlive();
    bool isAlive() const;

    ~ICoreCanvasObjectState();

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

ICoreProjectState.h#

src/ICoreBlocks/ICoreStudio/StudioManager/StateMachine/Objects/ICoreProjectState.h

ICoreProjectState#

ICoreProjectState.h:7 · class · pImpl · 15 declaration(s)

class ICoreProjectState {
public:
    explicit ICoreProjectState();

    // Order manipulation
    void setOrder(int o);
    void increaseOrder();
    void decreaseOrder();
    int getOrder() const;

    // StateSpace manipulation
    void addObjectState(ICoreCanvasObjectState* state);
    void deleteAllObjectStates();

    ICoreCanvasObjectState* getObjectStateByClassID(const std::string& classID) const;

    const std::vector<ICoreCanvasObjectState*>& getStateSpace() const;

    void printState() const;

    void resetToInitialState();
    void kill();
    void setAlive();
    bool isAlive() const;

    ~ICoreProjectState();

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