API — ICoreSDK/ICoreStudio/ExternalCommunications

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

ICoreActiveProjectFolder.h#

src/ICoreSDK/ICoreStudio/ExternalCommunications/ICoreActiveProjectFolder.h

False until a project has actually been opened -- the state the app starts in, before the startup behaviour has picked one, and the state it stays in when there was nothing to reopen. getActiveProjectFolderPath() is then just the documents folder, which is not a project and must not be written to; ICoreStudioSerialization checks this before any save.

ICoreActiveProjectFolder#

ICoreActiveProjectFolder.h:4 · class · 10 declaration(s)

class ICoreActiveProjectFolder {
public:
    static std::filesystem::path getActiveProjectFolderPath();

    // False until a project has actually been opened -- the state the app starts
    // in, before the startup behaviour has picked one, and the state it stays in
    // when there was nothing to reopen. getActiveProjectFolderPath() is then just
    // the documents folder, which is not a project and must not be written to;
    // ICoreStudioSerialization checks this before any save.
    static bool hasActiveProject();

    // Sets the active project's name (the folder/.iproj stem). Used by the Project
    // Navigator; getActiveProjectFolderPath() == documentsFolderPath / projectName.
    static void setProjectName(const std::string& name);

    // Empty when no project is open (the hasActiveProject() == false state).
    // Read by anything that has to put the active project back exactly as it
    // found it -- the regression sandbox does, and deriving the name from
    // getActiveProjectFolderPath().filename() would not survive a project name
    // that happens to match the documents folder's own.
    static const std::string& getProjectName();

    static void saveProjectSerializationToProjectFolder(const std::vector<std::string> &serializedProject);

    // Reads the project's .iproj. An empty result is AMBIGUOUS on its own and
    // the caller must not treat it as "an empty project": it is also what a file
    // that is present but unreadable (permissions, a lock, an IO error) returns.
    //
    // `readFailedOut`, when given, tells the two apart -- true means the file is
    // there and could not be read. ICoreStudioSerialization holds autosave off on that,
    // because replaying "nothing" and then autosaving it back is how a project
    // that was perfectly fine gets destroyed by being opened.
    static std::vector<std::string> loadProjectSerializationFromProjectFolder(
        bool* readFailedOut = nullptr);

    // The active project's .iproj path: <documents>/<project>/<project>.iproj.
    static std::filesystem::path projectSerializationFilePath();

    // True when that file is present on disk, whether or not it can be read.
    // This is the "a project file exists here" question, as distinct from "this
    // folder is a project" (ICoreProjectSession::isValidProjectFolder).
    static bool projectSerializationFileExists();
    // Mirrors an image into the project's Images subfolder as <pixmapClassId>.<ext>.
    // A no-op when a cached copy already exists under that id: ids are derived
    // from the picture, so the file that is there is already this image.
    static void copyImageToProjectFolder(const std::filesystem::path& originalImagePath, const std::string& pixmapClassId);
    static void loadAllImagesFromProjectFolder_OverwriteCachedInStateMachine();

    // Looks up the cached copy copyImageToProjectFolder() made for a given
    // pixmap cache key (ICoreImageViewPixmap::getPixmapId() / ICoreImageView::
    // getPixmapClassID()) - i.e. a file in the Images subfolder whose stem
    // matches the ID, whatever its original extension was. Returns an empty
    // path if the ID is unknown/"None" or no such file exists (e.g. the
    // project folder was never saved to, or the cached file was removed).
    static std::filesystem::path findCachedImagePath(const std::string& pixmapClassID);
};
};

ICoreDocumentsFolder.h#

src/ICoreSDK/ICoreStudio/ExternalCommunications/ICoreDocumentsFolder.h

ICoreDocumentsFolder#

ICoreDocumentsFolder.h:14 · class · 6 declaration(s)

Two folders with two different jobs, and the names are older than the split: * the DOCUMENTS folder is where the user's projects live -- Documents/<AppName> at startup, then repointed per project b...

class ICoreDocumentsFolder {
public:
    static long initializeDocumentsFolder();
    // static std::vector<std::string> readLogFile();
    // static void overwriteLogFile(const std::vector<std::string>& lines);
    static std::filesystem::path getDocumentsFolderPath();
    // Repoints documentsFolderPath (the parent of the active project). Used by the
    // Project Navigator so getActiveProjectFolderPath() == <this> / projectName.
    static void setDocumentsFolderPath(const std::filesystem::path& folderPath);

    // The per-OS application data folder, assigned once at initialize time:
    // ~/Library/Application Support/<AppName> on macOS,
    // %LOCALAPPDATA%\<AppName> on Windows, $XDG_DATA_HOME/<AppName> elsewhere.
    // Unlike documentsFolderPath (which the navigator repoints per project)
    // this never moves, so navigator state such as recentProjects.txt, the
    // preferences, the template mirror and the user block library live here.
    static std::filesystem::path getApplicationHomeFolderPath();

    static std::filesystem::path getSettingsFilePath();
    static std::filesystem::path getLogFilePath();
};
};

ICoreProjectCard.h#

src/ICoreSDK/ICoreStudio/ExternalCommunications/ProjectNavigator/ICoreProjectCard.h

ICoreProjectCard#

ICoreProjectCard.h:30 · class · bases public ICoreWidget · pImpl · 13 declaration(s)

ICoreProjectCard One row of the Project Navigator's recents list: the project's name, the folder it lives in, and a remove affordance that appears under the pointer.

class ICoreProjectCard : public ICoreWidget {
public:
    ICoreProjectCard(ICoreWidget* parent, const std::filesystem::path& projectFolderPath);
    ~ICoreProjectCard() override;

    [[nodiscard]] const std::filesystem::path& projectFolderPath() const;

    // Lowercased "<name> <parent path>", for the list's filter field.
    [[nodiscard]] const ICoreString& searchKey() const;

    // A folder that no longer holds its <name>.iproj still gets a row -- greyed,
    // labelled, and still removable -- rather than silently vanishing from a
    // list the user is looking at.
    void setProjectMissing(bool missing);

    [[nodiscard]] double hoverProgress() const;
    void setHoverProgress(double progress);

    ICoreSignal<> activated;
    ICoreSignal<> removeRequested;

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

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

ICoreProjectNavigator.h#

src/ICoreSDK/ICoreStudio/ExternalCommunications/ProjectNavigator/ICoreProjectNavigator.h

ICoreProjectNavigator#

ICoreProjectNavigator.h:40 · class · bases public ICoreWindow · pImpl · 4 declaration(s)

ICoreProjectNavigator The app's entry window: create a project, open one, or pick up a recent one.

class ICoreProjectNavigator : public ICoreWindow {
public:
    explicit ICoreProjectNavigator(ICoreWidget* parent = nullptr);
    ~ICoreProjectNavigator() override;

    // Opens the launcher straight on the new-project form rather than on the
    // recents list -- what "New Project..." elsewhere in the app asks for.
    void showNewProjectForm();

protected:
    // Escape backs out of the new-project form, and closes the launcher from the
    // recents list.
    bool keyPressed(const ICoreKeyEvent& event) override;

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

ICoreProjectSession.h#

src/ICoreSDK/ICoreStudio/ExternalCommunications/ProjectNavigator/ICoreProjectSession.h

ICoreProjectSession#

ICoreProjectSession.h:26 · class · final · 3 declaration(s)

ICoreProjectSession Which project the app is in, and the one way to change it.

class ICoreProjectSession final {
public:
    static ICoreProjectSession& instance();

    // What became of a requested switch. Callers care about more than pass/fail:
    // the launcher closes on Switched and AlreadyOpen, stays open on Failed so
    // another project can be picked, and leaves everything alone on Cancelled.
    enum class SwitchOutcome {
        Switched,      // the project is now the open one
        AlreadyOpen,   // it already was; nothing was reloaded
        Cancelled,     // the user backed out, or the folder could not be used
        Failed         // it could not be replayed; the editor is empty and autosave is held off
    };

    // Points the app at `projectFolderPath` and loads it. With createIfMissing
    // the folder is created and given an empty .iproj first (New Project);
    // otherwise it must already be a project folder.
    static SwitchOutcome switchToProjectFolder(ICoreNativeWidget* dialogParent,
                                               const std::filesystem::path& projectFolderPath,
                                               bool createIfMissing);

    // Persists -- or asks about -- the project currently in the editor, before it
    // is replaced. Returns false when the user cancels, which aborts the switch.
    static bool commitCurrentProject(ICoreNativeWidget* dialogParent);

    // True when folderPath/<folderName>.iproj exists (the project's serialized
    // file). This is the whole definition of "is a project folder", and startup
    // asks it too, before reopening the last project without a navigator.
    static bool isValidProjectFolder(const std::filesystem::path& folderPath);

    // The app is now in a different project, loaded and recorded as recent.
    // Raised synchronously, at the end of a successful switch.
    ICoreSignal<> onProjectChanged;

};

ICoreRecentProjects.h#

src/ICoreSDK/ICoreStudio/ExternalCommunications/ProjectNavigator/ICoreRecentProjects.h

ICoreRecentProjects#

ICoreRecentProjects.h:17 · class · 5 declaration(s)

ICoreRecentProjects Tiny persistence helper for the Project Navigator's "Recent Projects" list.

class ICoreRecentProjects {
public:
    // Most-recent first. Missing/deleted folders are filtered out on read.
    static std::vector<std::filesystem::path> getRecentProjects();

    // Promotes the path to the front (de-duplicated) and trims to the user's
    // configured maximum.
    static void addRecentProject(const std::filesystem::path& projectFolderPath);

    // Drops one entry from the list. This forgets the project, it does not touch
    // the folder on disk -- it is what the navigator's per-card remove does.
    static void removeRecentProject(const std::filesystem::path& projectFolderPath);

    static void clearRecentProjects();

    // Where the list is kept: <application home>/recentProjects.txt. Public so
    // that anything which has to leave this file exactly as it found it -- the
    // regression suite backs it up and restores it, because the application home
    // folder is deliberately NOT sandboxed -- can name it without restating the
    // filename somewhere else.
    static std::filesystem::path recentProjectsFilePath();
};
};

ICoreTemplateCard.h#

src/ICoreSDK/ICoreStudio/ExternalCommunications/ProjectNavigator/ICoreTemplateCard.h

ICoreTemplateCard#

ICoreTemplateCard.h:40 · class · bases public ICoreWidget · pImpl · 12 declaration(s)

ICoreTemplateCard One choice in a "start from" gallery: a picture of the diagram, its name, and a sentence saying what it is for.

class ICoreTemplateCard : public ICoreWidget {
public:
    // A template. The recipe is read once, here, to draw the thumbnail.
    //
    // The parent is an ICoreAnyWidget: ICoreNewTabPanel holds its gallery
    // container as a plain widget pointer and hands it in, so it cannot narrow
    // to ICoreWidget*.
    ICoreTemplateCard(ICoreNativeWidget* parent, const ICoreTemplateLibrary::Entry& entry);

    // The "start from nothing" choice: the same card with no template behind it,
    // so blank sits in the gallery as a peer of the templates rather than as a
    // checkbox somewhere else in the form. Its wording is the caller's, because
    // what "blank" produces differs by gallery -- an empty project on one, an
    // empty subsystem on the other.
    static ICoreTemplateCard* makeBlankCard(ICoreNativeWidget* parent, const ICoreString& title,
                                            const ICoreString& summary);

    // Empty for the blank card; otherwise the entry's id.
    [[nodiscard]] ICoreString templateId() const;

    // Everything about the card a gallery's filter field should match on, folded
    // to lower case once here rather than on every keystroke: what is written on
    // the card, plus the category and id, which are not drawn but are how a user
    // who knows the catalog would think to search it.
    [[nodiscard]] const ICoreString& searchKey() const;

    [[nodiscard]] bool isSelected() const;
    void setSelected(bool selected);

    [[nodiscard]] double hoverProgress() const;
    void setHoverProgress(double progress);

    // The user picked this card. The gallery deselects its siblings; a card
    // never assumes it won.
    ICoreSignal<> chosen;

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

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