API — ICoreSDK/ICoreStudio/StudioObjects/Panels/Terminal

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

ICoreTerminalSession.h#

src/ICoreSDK/ICoreStudio/StudioObjects/Panels/Terminal/ICoreTerminalSession.h

ICoreTerminalSession#

ICoreTerminalSession.h:45 · class · pImpl · 16 declaration(s)

A live shell under a pseudo-terminal, and the terminal state it is drawing.

class ICoreTerminalSession {
public:
    ICoreTerminalSession();
    ~ICoreTerminalSession();

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

    // --- setup, before start() ----------------------------------------------

    // Where the shell starts. Ignored after start(): moving a live shell is
    // the user's job, through the shell, which is the whole point of T5.3.
    void setWorkingDirectory(const ICoreString& directory);

    // --- running ------------------------------------------------------------

    // Starts the login shell at `columns` x `rows` cells. False if the shell
    // could not be started, with the reason already written to the screen so
    // the user sees it rather than an empty panel.
    bool start(int columns, int rows);

    [[nodiscard]] bool isRunning() const;

    // Take the shell down and bring a fresh one up in the same directory. What
    // the panel offers after a shell exits.
    void restart(int columns, int rows);

    // Cells, not pixels. Resizes the screen AND tells the pty, which is what
    // raises SIGWINCH so a full-screen program redraws itself.
    void setViewport(int columns, int rows);

    // Bytes from the view: keystrokes, paste, mouse reports.
    void write(const std::string& bytes);

    // Ctrl+C. Offered as a method because the panel has a button for it, and
    // because "interrupt" is clearer at a call site than a magic byte.
    void interrupt();

    // Clear the visible screen AND the scrollback, locally. Deliberately does
    // NOT run `clear` in the shell: injecting a command would land in whatever
    // the user was halfway through typing.
    void clearScreenAndScrollback();

    // --- what the view draws ------------------------------------------------

    // Owned here, borrowed by the view. Never null.
    [[nodiscard]] ICoreTerminalScreen* screen();

    // --- what the shell reports ---------------------------------------------

    // The shell's own cwd when it reports one (OSC 7); the start directory
    // otherwise. ⚠ An empty answer means "the shell has not said", never "/".
    [[nodiscard]] ICoreString workingDirectory() const;
    [[nodiscard]] ICoreString title() const;

    // The shell this platform will use, for display ("zsh", "bash", ...).
    [[nodiscard]] static ICoreString shellDisplayName();

    // --- notifications, all on the GUI thread -------------------------------

    // The screen changed. The view answers by repainting the dirty lines --
    // this deliberately carries no payload, because the screen already knows
    // exactly which rows moved and the view already knows how to ask.
    ICoreSignal<>            onScreenChanged;
    ICoreSignal<ICoreString> onWorkingDirectoryChanged;
    ICoreSignal<ICoreString> onTitleChanged;

    // The shell exited. Exit code, and whether a signal killed it.
    ICoreSignal<int, bool>   onClosed;

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

ICoreTerminalGridView.h#

src/ICoreSDK/ICoreStudio/StudioObjects/Panels/Terminal/UI/ICoreTerminalGridView.h

ICoreTerminalGridView#

ICoreTerminalGridView.h:35 · class · bases public ICoreWidget · pImpl · 29 declaration(s)

ICoreTerminalGridView -- draws an ICoreTerminalScreen.

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

    // Borrowed, not owned, and must outlive this view. Null is legal and
    // paints an empty terminal rather than crashing.
    void setScreen(ICoreTerminalScreen* screen);

    // --- T3.7: font and cell metrics ---------------------------------------

    // The monospace face comes from ICoreFontCatalog::fixedFont(); this sets
    // its size. Changing it re-measures the cell and re-reports the viewport.
    void setFontPointSize(double points);
    [[nodiscard]] double fontPointSize() const;

    // One cell, in device-independent pixels. Measured from the font's advance
    // width -- NOT assumed integral, because it is not on most faces at most
    // sizes, and rounding it per cell accumulates into a visible drift across
    // an 80-column line.
    [[nodiscard]] double cellWidth() const;
    [[nodiscard]] double cellHeight() const;

    // How many whole cells fit the widget right now. This is what the pty's
    // setViewport() wants -- cells, never pixels.
    [[nodiscard]] int viewportColumns() const;
    [[nodiscard]] int viewportRows() const;

    // Raised when the cell geometry changes -- a resize, or a font change --
    // carrying the new (columns, rows). The owner forwards it to
    // ICorePty::setViewport and to ICoreTerminalScreen::resize; this view
    // deliberately does neither itself, because it does not own either one.
    ICoreSignal<int, int> onViewportResized;

    // --- T3.2: damage ------------------------------------------------------

    // Repaint just the rows the screen has marked dirty, then clear its flags.
    // Call this after feeding bytes to the parser. Repainting everything on
    // every chunk is what makes a build log pin the GUI thread.
    void repaintDirtyLines();

    // --- T3.5: the scrollback viewport -------------------------------------

    // How many lines above the live screen the view is showing. 0 is pinned to
    // the bottom, which is where it returns on any keystroke and on any new
    // output -- a terminal that stays scrolled up while a build runs is a
    // terminal you have to chase.
    [[nodiscard]] int  scrollOffset() const;
    void setScrollOffset(int linesAboveBottom);
    void scrollToBottom();
    [[nodiscard]] bool isScrolledBack() const;

    // --- §T4: input --------------------------------------------------------

    // The bytes this view wants written to the pty: keystrokes, paste, mouse
    // reports. The view has no pty and never will -- the owner connects this
    // to ICorePty::write, which is what keeps the view testable and stops it
    // owning a process.
    ICoreSignal<std::string> onBytesToPty;

    // Paste the clipboard, framed per the screen's bracketed-paste mode.
    // Exposed so a context menu or a shortcut can call it.
    void pasteFromClipboard();

    // --- T3.4: selection ---------------------------------------------------

    // The selected text, rows joined by newlines and trailing blanks trimmed
    // off each. Empty when nothing is selected.
    [[nodiscard]] std::string selectedText() const;

    [[nodiscard]] bool hasSelection() const;
    void clearSelection();

    // Put the selection on the clipboard. A no-op when there is none -- it
    // deliberately does NOT fall back to copying everything, which is what a
    // Ctrl+C mapped to "copy or interrupt" would otherwise do on an empty
    // selection.
    void copySelectionToClipboard();

    // --- T3.3: cursor ------------------------------------------------------

    // Blinking is on by default and stops while the view is unfocused, where
    // the cursor is drawn hollow instead. A blinking cursor in a panel nobody
    // is typing into is just a distraction that also costs a repaint a second.
    void setCursorBlinkEnabled(bool enabled);

protected:
    void paintContent(ICorePainter& painter, const ICoreRect& dirty) override;
    void resized(const ICoreSizeF& newSize, const ICoreSizeF& oldSize) override;
    void focusGained(const ICoreFocusEvent& event) override;
    void focusLost(const ICoreFocusEvent& event) override;

    // ⚠ keyPressed returns TRUE for almost everything, and that is the point
    // of row T4.2. A terminal must swallow Ctrl+C, Ctrl+D, Ctrl+Z, Tab and the
    // arrows and put them on the wire as bytes; if an application shortcut
    // claims one first, the byte never ships and the terminal looks hung with
    // no diagnostic anywhere.
    bool keyPressed(const ICoreKeyEvent& event) override;

    bool mousePressed(const ICoreMouseEvent& event) override;
    bool mouseReleased(const ICoreMouseEvent& event) override;
    bool mouseMoved(const ICoreMouseEvent& event) override;
    bool wheelScrolled(const ICoreWheelEvent& event) override;

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

ICoreTerminalMenuPanel.h#

src/ICoreSDK/ICoreStudio/StudioObjects/Panels/Terminal/UI/ICoreTerminalMenuPanel.h

ICoreTerminalMenuPanel#

ICoreTerminalMenuPanel.h:32 · class · bases public ICoreWidget · pImpl · 3 declaration(s)

Left-panel page holding a REAL TERMINAL: a login shell under a pseudo- terminal, drawn as a cell grid.

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

protected:
    // The panel lives in an ICoreStackedLayout; start the shell the first time
    // it becomes visible, and put focus on the grid so typing goes to the
    // shell rather than nowhere.
    void shown() override;

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