#3549 scripting: add extended syntax highlighting

Signed-off-by: Patrizio Bekerle <patrizio@bekerle.com>

Author: pbek

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## 26.4.9
 
+- Extended the **scripting engine's syntax highlighting** support with **custom
+  colors and styles**: `addHighlightingRule` now accepts an optional format map
+  with `foregroundColor`, `backgroundColor`, `bold`, `italic`, `underline`, and
+  `fontSize` properties, so scripts can define their own highlight colors instead
+  of being limited to the predefined highlighting states
+  (for [#3549](https://github.com/pbek/QOwnNotes/issues/3549))
+- Added a new **`highlightingHook`** scripting hook that is called for each text
+  block during syntax highlighting, allowing scripts to perform dynamic,
+  context-aware highlighting with custom colors and styles
+  (for [#3549](https://github.com/pbek/QOwnNotes/issues/3549))
 - Fixed a possible **startup crash** when restoring the last opened note from
   **note history** while the **note tree** was enabled: history restoration
   searched the tree by note name and could match a folder item with the same label

docs/scripting/examples/custom-highlighting.qml

@@ -0,0 +1,87 @@
+import QtQml 2.0
+import QOwnNotesTypes 1.0
+
+/**
+ * This script demonstrates the custom highlighting features:
+ * 1. Static rules with custom colors/styles via addHighlightingRule()
+ * 2. Dynamic per-block highlighting via highlightingHook()
+ */
+Script {
+    function init() {
+        // Highlight "TODO" with bold white text on a red background
+        script.addHighlightingRule("TODO", "TODO", -1, 0, 0, {
+            "foregroundColor": "#ffffff",
+            "backgroundColor": "#cc0000",
+            "bold": true
+        });
+
+        // Highlight "DONE" with green strikethrough-like italic text
+        script.addHighlightingRule("DONE", "DONE", -1, 0, 0, {
+            "foregroundColor": "#22aa22",
+            "italic": true
+        });
+
+        // Highlight lines starting with ">" and containing "IMPORTANT"
+        // using blockquote state (18) with a custom red foreground color
+        script.addHighlightingRule("^>.*IMPORTANT.*", "IMPORTANT", 18, 0, 0, {
+            "foregroundColor": "#ff4444"
+        });
+
+        // Highlight "@username" mentions with a custom color and underline
+        script.addHighlightingRule("@\\w+", "@", -1, 0, 0, {
+            "foregroundColor": "#3366cc",
+            "underline": true
+        });
+    }
+
+    /**
+     * Dynamic per-block highlighting hook.
+     *
+     * This function is called for every text block in the editor during
+     * syntax highlighting. It receives the block text and the previous
+     * block's highlighter state, allowing context-aware highlighting.
+     *
+     * @param text the text of the current block
+     * @param previousBlockState the state of the previous block (-1 for the first block)
+     * @return an array of highlight range objects
+     */
+    function highlightingHook(text, previousBlockState) {
+        var highlights = [];
+
+        // Highlight "#tag" style tags with a custom teal color
+        var tagRegex = /#[a-zA-Z]\w*/g;
+        var match;
+        while ((match = tagRegex.exec(text)) !== null) {
+            highlights.push({
+                "start": match.index,
+                "length": match[0].length,
+                "foregroundColor": "#008080",
+                "bold": true
+            });
+        }
+
+        // Highlight "FIXME" and "HACK" keywords with red underlined text
+        var keywordRegex = /\b(FIXME|HACK)\b/g;
+        while ((match = keywordRegex.exec(text)) !== null) {
+            highlights.push({
+                "start": match.index,
+                "length": match[0].length,
+                "foregroundColor": "#ff0000",
+                "underline": true,
+                "bold": true
+            });
+        }
+
+        // Highlight dates in YYYY-MM-DD format with a purple color
+        var dateRegex = /\b\d{4}-\d{2}-\d{2}\b/g;
+        while ((match = dateRegex.exec(text)) !== null) {
+            highlights.push({
+                "start": match.index,
+                "length": match[0].length,
+                "foregroundColor": "#8855cc"
+            });
+        }
+
+        return highlights;
+    }
+}

docs/scripting/examples/highlighting.qml

@@ -10,5 +10,59 @@ Script {
         // capturingGroup 1 means the expression from the first bracketed part of the pattern will be highlighted
         // maskedGroup -1 means that no masking should be done
         script.addHighlightingRule("^.{32}(.+)", "", 24, 1, -1);
+
+        // Highlight "IMPORTANT" with custom colors: red bold text on a yellow background
+        // The 6th parameter is a map with custom format properties:
+        //   foregroundColor, backgroundColor, bold, italic, underline, fontSize
+        // Use state -1 (NoState) to use only custom formatting without a predefined state
+        script.addHighlightingRule("IMPORTANT", "IMPORTANT", -1, 0, 0, {
+            "foregroundColor": "#ff0000",
+            "backgroundColor": "#ffff00",
+            "bold": true
+        });
+
+        // Highlight "NOTE:" with custom italic green text
+        script.addHighlightingRule("NOTE:", "NOTE:", -1, 0, 0, {
+            "foregroundColor": "#00aa00",
+            "italic": true
+        });
+    }
+
+    /**
+     * This hook is called for each text block during syntax highlighting.
+     * It allows context-aware, dynamic highlighting that goes beyond
+     * static regex rules.
+     *
+     * @param text - the text of the current block being highlighted
+     * @param previousBlockState - the highlighter state of the previous block
+     *     (-1 if this is the first block)
+     * @return an array of highlight range objects, each with:
+     *     start {int} - start position in the text
+     *     length {int} - number of characters to highlight
+     *     state {int} - the HighlighterState to use (optional, -1 for custom only)
+     *     foregroundColor {string} - foreground color (optional)
+     *     backgroundColor {string} - background color (optional)
+     *     bold {bool} - bold (optional)
+     *     italic {bool} - italic (optional)
+     *     underline {bool} - underline (optional)
+     *     fontSize {int} - font point size (optional)
+     */
+    function highlightingHook(text, previousBlockState) {
+        var highlights = [];
+
+        // Example: highlight all occurrences of "FIXME" with red underline
+        var re = /FIXME/g;
+        var match;
+        while ((match = re.exec(text)) !== null) {
+            highlights.push({
+                "start": match.index,
+                "length": match[0].length,
+                "foregroundColor": "#ff0000",
+                "underline": true,
+                "bold": true
+            });
+        }
+
+        return highlights;
     }
 }

src/helpers/qownnotesmarkdownhighlighter.cpp

@@ -21,6 +21,7 @@
 #include <QApplication>
 #include <QColor>
 #include <QDebug>
+#include <QFont>
 #include <QObject>
 #include <QRegularExpression>
 #include <QRegularExpressionMatch>
@@ -109,6 +110,10 @@ void QOwnNotesMarkdownHighlighter::highlightBlock(const QString &text) {
 #endif
 
         highlightScriptingRules(ScriptingService::instance()->getHighlightingRules(), text);
+
+        // Call the per-block highlightingHook in scripts (only invoked if at
+        // least one script provides the hook, checked via cached flag)
+        highlightScriptingHook(text);
     }
 
     // Only check for encryption end marker if we're highlighting encrypted text
@@ -134,18 +139,49 @@ void QOwnNotesMarkdownHighlighter::highlightScriptingRules(
         auto iterator = rule.pattern.globalMatch(text);
         const uint8_t capturingGroup = rule.capturingGroup;
         const uint8_t maskedGroup = rule.maskedGroup;
-        const QTextCharFormat &format = _formats[rule.state];
 
-        // find and format all occurrences
+        // Build the format: use custom format if provided, otherwise use the
+        // predefined format for the given state
+        QTextCharFormat format;
+        if (rule.hasCustomFormat) {
+            // Start from the state format if a valid state was specified
+            if (rule.state != NoState) {
+                format = _formats[rule.state];
+            }
+
+            // Override with custom properties
+            if (!rule.foregroundColor.isEmpty()) {
+                format.setForeground(QColor(rule.foregroundColor));
+            }
+            if (!rule.backgroundColor.isEmpty()) {
+                format.setBackground(QColor(rule.backgroundColor));
+            }
+            if (rule.bold) {
+                format.setFontWeight(QFont::Bold);
+            }
+            if (rule.italic) {
+                format.setFontItalic(true);
+            }
+            if (rule.underline) {
+                format.setFontUnderline(true);
+            }
+            if (rule.fontSize > 0) {
+                format.setFontPointSize(rule.fontSize);
+            }
+        } else {
+            format = _formats[rule.state];
+        }
+
+        // Find and format all occurrences
         while (iterator.hasNext()) {
             QRegularExpressionMatch match = iterator.next();
 
-            // if there is a capturingGroup set then first highlight
+            // If there is a capturingGroup set then first highlight
             // everything as MaskedSyntax and highlight capturingGroup
             // with the real format
             if (capturingGroup > 0) {
                 QTextCharFormat currentMaskedFormat = maskedFormat;
-                // set the font size from the current rule's font format
+                // Set the font size from the current rule's font format
                 if (format.fontPointSize() > 0) {
                     currentMaskedFormat.setFontPointSize(format.fontPointSize());
                 }
@@ -160,6 +196,69 @@ void QOwnNotesMarkdownHighlighter::highlightScriptingRules(
     }
 }
 
+/**
+ * Calls the highlightingHook in all script components for the current text
+ * block and applies the returned highlight ranges
+ */
+void QOwnNotesMarkdownHighlighter::highlightScriptingHook(const QString &text) {
+    ScriptingService *scriptingService = ScriptingService::instance();
+
+    if (!scriptingService->highlightingHookExists()) {
+        return;
+    }
+
+    const QVariantList highlights =
+        scriptingService->callHighlightingHook(text, previousBlockState());
+
+    for (const QVariant &item : highlights) {
+        const QVariantMap m = item.toMap();
+        const int start = m.value(QStringLiteral("start")).toInt();
+        const int length = m.value(QStringLiteral("length")).toInt();
+
+        if (length <= 0) {
+            continue;
+        }
+
+        // Determine the format from the state or custom properties
+        const int state = m.value(QStringLiteral("state"), -1).toInt();
+        QTextCharFormat format;
+
+        if (state >= 0) {
+            format = _formats[static_cast<HighlighterState>(state)];
+        }
+
+        // Apply custom format overrides
+        const QString fg = m.value(QStringLiteral("foregroundColor")).toString();
+        if (!fg.isEmpty()) {
+            format.setForeground(QColor(fg));
+        }
+
+        const QString bg = m.value(QStringLiteral("backgroundColor")).toString();
+        if (!bg.isEmpty()) {
+            format.setBackground(QColor(bg));
+        }
+
+        if (m.value(QStringLiteral("bold")).toBool()) {
+            format.setFontWeight(QFont::Bold);
+        }
+
+        if (m.value(QStringLiteral("italic")).toBool()) {
+            format.setFontItalic(true);
+        }
+
+        if (m.value(QStringLiteral("underline")).toBool()) {
+            format.setFontUnderline(true);
+        }
+
+        const qreal fontSize = m.value(QStringLiteral("fontSize")).toReal();
+        if (fontSize > 0) {
+            format.setFontPointSize(fontSize);
+        }
+
+        setFormat(start, length, format);
+    }
+}
+
 void QOwnNotesMarkdownHighlighter::updateCachedRegexes(const QString &newExt) {
     _regexTagStyleLink = QRegularExpression(R"(<([^\s`][^`]*?\.)" + newExt + R"()>)");
     _regexBracketLink = QRegularExpression(R"(\[[^\[\]]+\]\((\S+\.)" + newExt + R"(|.+?\.)" +

src/helpers/qownnotesmarkdownhighlighter.h

@@ -50,6 +50,15 @@ class QOwnNotesMarkdownHighlighter : public MarkdownHighlighter {
         HighlighterState state = NoState;
         uint8_t capturingGroup = 0;
         uint8_t maskedGroup = 0;
+
+        // Custom format fields for script-defined colors and styles
+        bool hasCustomFormat = false;
+        QString foregroundColor;
+        QString backgroundColor;
+        bool bold = false;
+        bool italic = false;
+        bool underline = false;
+        qreal fontSize = 0;
     };
 
    protected:
@@ -82,4 +91,5 @@ class QOwnNotesMarkdownHighlighter : public MarkdownHighlighter {
     QHash<QString, bool> _wikiLinkCache;
     void highlightScriptingRules(const QVector<ScriptingHighlightingRule> &rules,
                                  const QString &text);
+    void highlightScriptingHook(const QString &text);
 };