API — ICoreEssentials/UI/Text

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

ICoreSyntaxHighlighter.h#

src/ICoreEssentials/UI/Text/ICoreSyntaxHighlighter.h

ICoreSyntaxHighlighter#

ICoreSyntaxHighlighter.h:31 · class · bases public QSyntaxHighlighter · 1 declaration(s)

⚠ FROZEN QT LAYER (P8.5) — DO NOT EDIT, DO NOT ADD MEMBERS.

class ICoreSyntaxHighlighter : public QSyntaxHighlighter {
protected:
    // Base only — the hierarchy is constructed through
    // ICoreSyntaxHighlighterBase.
    explicit ICoreSyntaxHighlighter(QTextDocument* parent = nullptr);
};
};

ICoreSyntaxHighlighterBase.h#

src/ICoreEssentials/UI/Text/ICoreSyntaxHighlighterBase.h

ICoreSyntaxHighlighterBase#

ICoreSyntaxHighlighterBase.h:39 · class · bases public ICoreSyntaxHighlighter · pImpl · 15 declaration(s)

ICoreSyntaxHighlighterBase - owns ALL styling (single source of truth) - provides rule engine THIS IS THE PROJECT'S SYNTAX HIGHLIGHTER COMPONENT (task C9).

class ICoreSyntaxHighlighterBase : public ICoreSyntaxHighlighter {
public:
    // E6.1's ctor: the editors mint the handle (documentHandle()), so a
    // subclass's constructor line names zero Qt.
    explicit ICoreSyntaxHighlighterBase(const ICoreTextDocumentHandle& document);

    // Migration ctor — F4b retires the callers file by file; new highlighter
    // code takes the handle form above.
    explicit ICoreSyntaxHighlighterBase(QTextDocument* parent = nullptr);

    // Out of line: Impl is incomplete here, so the unique_ptr's deleter cannot
    // be instantiated in this header. There was no user-declared destructor
    // before H4.45 -- the implicit one was fine while every member was a
    // complete type.
    ~ICoreSyntaxHighlighterBase() override;

    // =========================
    // THE RULE ENGINE -- PUBLIC SINCE H4.45
    // =========================
    //
    // ⚠ THIS SURFACE WAS `protected:`, AND MAKING IT PUBLIC IS THE ROW RATHER
    // THAN A SIDE EFFECT OF IT. The engine and the palette were protected DATA
    // and protected NON-VIRTUAL helpers; the header surface rule bans both and
    // exemption 2 does not reach them, since it covers protected VIRTUAL
    // declarations only. Nine language highlighters in src/ICoreSDK drive this
    // engine across a module boundary -- so what it is, is public API that had
    // been written down as an inheritance detail. It is spelled that way now.
    //
    // Not made virtual to claim exemption 2: these are CALLED, not overridden,
    // and adding vtable entries to buy the guard's silence is the abuse the
    // guidelines warn about.

    // The token classes this engine paints. A subclass names the CLASS, never
    // the colour: the base owns the format each token wears and re-derives all
    // thirteen from the theme on every switch (initTheme), so a highlighter
    // cannot go stale holding a colour of its own.
    enum class Token {
        Keyword, Type, String, Char, Comment, Number, Function,
        Class, Macro, Attribute, Operator, Lifetime, Builtin
    };

    // Register a pattern. Replaces `rules.push_back({pattern, fmtX})`, which is
    // what all 40 external uses of the old `rules` member were -- one shape.
    void addRule(const ICoreRegex& pattern, Token token);

    // For a subclass with a format of its own (ICoreScriptEditorHighlighter's
    // fmtHandle / fmtPort / fmtSymbol) rather than one of the thirteen.
    void addRule(const ICoreRegex& pattern, const ICoreTextCharFormat& format);

    void clearRules();

    // The format `token` wears under the active theme. NOT named format(): that
    // would hide the inherited QSyntaxHighlighter::format(int) behind an
    // overload nobody asked for -- the overload-hiding trap this tier has paid
    // for before. charFormatAt() remains the way to read a run's own format.
    [[nodiscard]] ICoreTextCharFormat tokenFormat(Token token) const;

    void applyRules(const ICoreString& text);

    void applyRegex(const ICoreString& text,
                    const ICoreRegex& re,
                    const ICoreTextCharFormat& fmt);
    void applyRegex(const ICoreString& text, const ICoreRegex& re, Token token);

    // E6.1: the ICore-typed run surface. Declaring setFormat here HIDES the
    // inherited Qt overloads, so the `using` re-exposes them for the
    // still-unflipped subclasses (F4b walks them off it); resolution is
    // unambiguous both ways because an exact match outranks the cushion
    // conversion in either direction. charFormatAt is a distinct name, not an
    // overload of Qt's format(int): the two differ only in return type, which
    // overloading cannot express.
    using ICoreSyntaxHighlighter::setFormat;
    void setFormat(int start, int count, const ICoreTextCharFormat& format);
    void setFormat(int start, int count, Token token);
    [[nodiscard]] ICoreTextCharFormat charFormatAt(int position) const;

protected:
    // Qt's entry point, taken over here once for the whole hierarchy, and
    // `final` so no subclass can re-open the QString signature.
    //
    // THIS IS WHAT RETIRES THE LARGEST HOLD-OUT BLOCK IN THE PLAN'S SECTION 1
    // CENSUS. Twenty-six of the forty remaining QString occurrences in the
    // tree were `highlightBlock(const QString&)` -- thirteen declarations and
    // thirteen definitions -- and every one was correctly classified H6:
    // Qt declares the signature, so there is no call site left to migrate and
    // the occurrence is permanent. What that classification cannot see, and
    // what C6 found first for QFileDialog, is that "permanent" means
    // "permanent while QT declares it". Interposing one override here makes
    // the signature THIS project's, and the thirteen subclasses become
    // ordinary migratable code. Re-derive the permanent/transient split
    // against the CURRENT signature, never against the note that classified it.
    void highlightBlock(const QString& text) final;

    // What subclasses implement instead. Same name deliberately: it is the
    // domain's word and Qt's, and the overload set is unambiguous because the
    // only call is the forwarder's, whose argument is an exact ICoreString
    // match -- an exact match outranks the user-defined conversion the QString
    // overload would need.
    virtual void highlightBlock(const ICoreString& text) = 0;

    // E6.1: the ICore-typed run surface. Declaring setFormat here HIDES the
    // inherited Qt overloads, so the `using` re-exposes them for the
    // still-unflipped subclasses (F4b walks them off it); resolution is
    // unambiguous both ways because an exact match outranks the cushion
    // conversion in either direction. charFormatAt is a distinct name, not an
    // overload of Qt's format(int): the two differ only in return type, which
    // overloading cannot express. It hands back the FULL format the run
    // already carries (see ICoreTextCharFormat.h on merge fidelity).
    // setCurrentBlockState/previousBlockState need no forwarders: their
    // signatures are int-only, so an unqualified call names zero Qt already.

    // Re-reads every character format from the syntax tokens. Virtual so a
    // subclass with formats of its own refreshes those in the same pass -- the
    // base constructor subscribes this to themeChanged, and a format that is
    // not refreshed there keeps the previous theme's colour.
    virtual void initTheme();

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

ICoreTextBlock.h#

src/ICoreEssentials/UI/Text/ICoreTextBlock.h

ICoreTextBlock#

ICoreTextBlock.h:21 · class · 14 declaration(s)

One paragraph/line of a text document, as a value handle.

class ICoreTextBlock {
public:
    // An invalid block -- isValid() false, like walking past the last one.
    ICoreTextBlock();

    // Wrapper-zone inbound seam (the editors and icoreQt() build these).
    ICoreTextBlock(const QTextBlock& block);

    ICoreTextBlock(const ICoreTextBlock& other);
    ICoreTextBlock(ICoreTextBlock&& other) noexcept;
    ICoreTextBlock& operator=(const ICoreTextBlock& other);
    ICoreTextBlock& operator=(ICoreTextBlock&& other) noexcept;
    ~ICoreTextBlock();

    [[nodiscard]] bool isValid() const;
    [[nodiscard]] bool isVisible() const;
    [[nodiscard]] int blockNumber() const;

    // First character's position in the whole document.
    [[nodiscard]] int position() const;

    [[nodiscard]] ICoreString text() const;

    // The following block; invalid past the last one, so the gutter's loop is
    // `for (auto b = firstBlock(); b.isValid(); b = b.next())`.
    [[nodiscard]] ICoreTextBlock next() const;

    // The seam, per §1. Call icoreQt() from a .cpp rather than reaching in.
    //
    // ⚠ OUT OF LINE SINCE H4.4x. icoreQt() is inline and calls this, so every
    // unwrap at a paint site is now a call into the library instead of a field
    // read. That cost was priced and accepted for every non-template type at
    // the guidelines (2026-08-14) -- do not re-litigate it here.
    [[nodiscard]] const void* nativeStorage() const;

    // Public only so the .cpp can pin them. Measured, not assumed:
    // QTextBlock is {QTextDocumentPrivate*, int} -- 16 bytes / align 8 on
    // this tree's Qt 6.10.2, macOS arm64. Non-polymorphic.
    static constexpr std::size_t kNativeStorageSize = 16;
    static constexpr std::size_t kNativeStorageAlign = 8;

};

ICoreTextCharFormat.h#

src/ICoreEssentials/UI/Text/ICoreTextCharFormat.h

ICoreTextCharFormat#

ICoreTextCharFormat.h:26 · class · 13 declaration(s)

A character-run format: what a syntax highlighter paints a token with.

class ICoreTextCharFormat {
public:
    ICoreTextCharFormat();

    void setForeground(const ICoreColor& color);
    void setBold(bool bold);
    void setItalic(bool italic);
    void setUnderlineStyle(ICoreTextUnderlineStyle style);
    void setUnderlineColor(const ICoreColor& color);

    // Implicit on purpose — the migration cushion, ICoreIcon's QIcon shape:
    // an unflipped highlighter's QTextCharFormat still flows into
    // applyRegex/setFormat while F4b walks the 38 files. Wrapper zone only;
    // a Studio file naming QTextCharFormat is exactly what F4b removes.
    ICoreTextCharFormat(const QTextCharFormat& format);

    ICoreTextCharFormat(const ICoreTextCharFormat& other);
    ICoreTextCharFormat(ICoreTextCharFormat&& other) noexcept;
    ICoreTextCharFormat& operator=(const ICoreTextCharFormat& other);
    ICoreTextCharFormat& operator=(ICoreTextCharFormat&& other) noexcept;
    ~ICoreTextCharFormat();

    // The seam, per §1. Call icoreQt() from a .cpp rather than reaching in.
    //
    // ⚠ OUT OF LINE SINCE H4.4x. icoreQt() is inline and calls this, so every
    // unwrap at a paint site is now a call into the library instead of a field
    // read. That cost was priced and accepted for every non-template type at
    // the guidelines (2026-08-14) -- do not re-litigate it here.
    [[nodiscard]] const void* nativeStorage() const;

    // Public only so the .cpp can pin them. Measured, not assumed:
    // QTextCharFormat is QTextFormat's {QSharedDataPointer, qint32} — 16
    // bytes / align 8 on this tree's Qt 6.10.2, macOS arm64. Non-polymorphic.
    static constexpr std::size_t kNativeStorageSize = 16;
    static constexpr std::size_t kNativeStorageAlign = 8;

};

File-scope declarations#

// How an underlined run is drawn. Mapped to the toolkit by a switch in the
// .cpp, so the numeric values here are this project's own — nothing to pin.
enum class ICoreTextUnderlineStyle {
    None,
    Wave,   // the "won't run" squiggle
};

ICoreTextCursor.h#

src/ICoreEssentials/UI/Text/ICoreTextCursor.h

ICoreTextCursor#

ICoreTextCursor.h:24 · class · 16 declaration(s)

An editing position in a text document, as a value handle.

class ICoreTextCursor {
public:
    // A null cursor.
    ICoreTextCursor();

    // A cursor at the start of the editor's document.
    explicit ICoreTextCursor(const ICoreTextDocumentHandle& document);

    // Wrapper-zone inbound seam (the editors and icoreQt() build these).
    ICoreTextCursor(const QTextCursor& cursor);

    ICoreTextCursor(const ICoreTextCursor& other);
    ICoreTextCursor(ICoreTextCursor&& other) noexcept;
    ICoreTextCursor& operator=(const ICoreTextCursor& other);
    ICoreTextCursor& operator=(ICoreTextCursor&& other) noexcept;
    ~ICoreTextCursor();

    // Absolute position in the document.
    [[nodiscard]] int position() const;

    enum class MoveMode {
        Move,         // move the anchor with the position (no selection)
        KeepAnchor,   // leave the anchor: the span in between is selected
    };
    void setPosition(int position, MoveMode mode = MoveMode::Move);

    [[nodiscard]] ICoreTextBlock block() const;

    // Position relative to the start of the caret's block/line.
    [[nodiscard]] int positionInBlock() const;

    // Replaces the selection if there is one, as the toolkit does.
    void insertText(const ICoreString& text);

    void selectDocument();

    // The one block-format the script editor needs: proportional line height,
    // in percent of the font's natural height, MERGED so the blocks keep
    // their other properties. 100 is the natural height.
    void mergeLineHeightPercent(int percent);

    // The seam, per §1. Call icoreQt() from a .cpp rather than reaching in.
    //
    // ⚠ OUT OF LINE SINCE H4.4x. icoreQt() is inline and calls this, so every
    // unwrap at a paint site is now a call into the library instead of a field
    // read. That cost was priced and accepted for every non-template type at
    // the guidelines (2026-08-14) -- do not re-litigate it here.
    [[nodiscard]] const void* nativeStorage() const;

    // Public only so the .cpp can pin them. Measured, not assumed:
    // QTextCursor is one shared-data pointer -- 8 bytes / align 8 on this
    // tree's Qt 6.10.2, macOS arm64. Non-polymorphic.
    static constexpr std::size_t kNativeStorageSize = 8;
    static constexpr std::size_t kNativeStorageAlign = 8;

};

ICoreTextDocumentHandle.h#

src/ICoreEssentials/UI/Text/ICoreTextDocumentHandle.h

ICoreTextDocumentHandle#

ICoreTextDocumentHandle.h:22 · class · 5 declaration(s)

An opaque pass-through: the document an editor owns, on its way to the syntax highlighter that will watch it.

class ICoreTextDocumentHandle {
public:
    ICoreTextDocumentHandle();

    // Wrapper-zone side: the editors construct one from their Impl's document.
    explicit ICoreTextDocumentHandle(QTextDocument* document);

    [[nodiscard]] bool isNull() const;

    // The seam. Call from a .cpp inside a sanctioned zone only.
    [[nodiscard]] QTextDocument* qt() const;

    // Public only so the .cpp can pin them. A pointer, measured rather than
    // assumed, like every other buffer in this tier.
    static constexpr std::size_t kNativeStorageSize = sizeof(void*);
    static constexpr std::size_t kNativeStorageAlign = alignof(void*);

};