Class SBGUIHtmlFilter

ClassList > SBGUIHtmlFilter

SBGUIHtmlFilter Lightweight, application-wide HTML link router for QLabel, QTextBrowser, and QTextEdit.More...

• #include <SBGUIHtmlFilter.hpp>

Public Types

Type	Name
typedef std::function< void(const QString &href)>	LinkHandler
typedef std::function< void(const QString &href)>	LinkHoverHandler

Public Static Functions

Type	Name
void	activateLink (const QString & href) Convenience helpers to invoke handlers manually.
void	enableAutoWire (bool on=true) Auto-wire ALL QLabel, QTextBrowser, and QTextEdit widgets in the app.
void	hoverLink (const QString & href) Notifies the registered hover handler of a hyperlink hover event.
void	install (QApplication * app=nullptr) Install once; safe to call multiple times.
QString	makeActionLink (const SBUUID & uuid, const QString & displayName) Convenience helpers to build links.
QString	makePrompLink (const SBUUID & uuid, const QString & displayName="Ask SAMSON AI") Creates an HTML link that triggers an AI prompt action identified by a UUID.
QString	makePrompLink (const QString & prompt, const QString & displayName="Ask SAMSON AI") Creates an HTML link that triggers an AI prompt with the given text.
QString	makeUrlLink (const QUrl & url, const QString & displayName, const QString & utm_content, const QString & utm_source=QStringLiteral("SAMSON")) Constructs an HTML anchor element linking to a URL, optionally with UTM parameters.
void	setHoverHandler (LinkHoverHandler handler) Sets the global handler invoked when a hyperlink is hovered.
void	setLinkHandler (LinkHandler handler) Set global handlers.
void	wireLabel (QLabel * label) Wire a single QLabel explicitly.
void	wireTextBrowser (QTextBrowser * browser) Wire a single QTextBrowser explicitly.
void	wireTextEdit (QTextEdit * edit) Wire a single QTextEdit explicitly (adds a viewport event filter).

Detailed Description

Features * Routes <a href="...">...</a> to global click/hover handlers * Auto-wires all QLabel/QTextBrowser/QTextEdit (optional), or wire individually * Optional global pointing-hand cursor on link hover

Notes * Per-widget opt-out: setProperty("sb_skip_autolink", true) * For QTextEdit, installs a viewport event filter and uses anchorAt() for hover/click.

Public Types Documentation

typedef LinkHandler

using SBGUIHtmlFilter::LinkHandler =  std::function<void(const QString& href)>;

---

typedef LinkHoverHandler

using SBGUIHtmlFilter::LinkHoverHandler =  std::function<void(const QString& href)>;

---

Public Static Functions Documentation

function activateLink

Convenience helpers to invoke handlers manually.

static void SBGUIHtmlFilter::activateLink (
    const QString & href
) 

Activates a hyperlink by invoking the registered handler or performing a default action.

If a custom link handler has been set, it is called with the href. Otherwise, HTTP and HTTPS URLs are opened in the default web browser.

Parameters:

• href The href of the link to activate.

---

function enableAutoWire

Auto-wire ALL QLabel, QTextBrowser, and QTextEdit widgets in the app.

static void SBGUIHtmlFilter::enableAutoWire (
    bool on=true
) 

Enables or disables the automatic wiring feature for all widgets.

When enabled, the filter automatically wires QLabel, QTextBrowser, and QTextEdit instances as they appear in the UI.

Parameters:

• on True to enable automatic wiring; false to disable.

---

function hoverLink

Notifies the registered hover handler of a hyperlink hover event.

static void SBGUIHtmlFilter::hoverLink (
    const QString & href
) 

If a hover handler has been set, it is called with the href of the hovered link. An empty href indicates that the cursor has left a link.

Parameters:

• href The href of the currently hovered link, or an empty string if no link is hovered.

---

function install

Install once; safe to call multiple times.

static void SBGUIHtmlFilter::install (
    QApplication * app=nullptr
) 

Installs the SBGUIHtmlFilter into the given application.

This creates and registers a global event filter that enables HTML link handling. If an application pointer is not provided, the current QApplication instance is resolved.

Parameters:

• app Optional pointer to the QApplication; if nullptr, the current application is used.

---

function makeActionLink

Convenience helpers to build links.

static QString SBGUIHtmlFilter::makeActionLink (
    const SBUUID & uuid,
    const QString & displayName
) 

Creates an HTML link that invokes a custom action identified by a UUID.

<a href="action://?uuid=UUID" LINK_STYLE>displayName</a>

The link uses the "action://" scheme with the provided UUID as a query parameter.

Parameters:

• uuid The UUID of the action to invoke.
• displayName Text displayed for the hyperlink.

Returns:

The formatted HTML anchor as a QString.

---

function makePrompLink [1/2]

Creates an HTML link that triggers an AI prompt action identified by a UUID.

static QString SBGUIHtmlFilter::makePrompLink (
    const SBUUID & uuid,
    const QString & displayName="Ask SAMSON AI"
) 

<a href="ai://?action=UUID" LINK_STYLE>Ask SAMSON AI</a>

The link uses the custom "ai://" scheme with the provided action UUID.

Parameters:

• uuid The UUID of the AI action to trigger.
• displayName Text displayed for the hyperlink.

Returns:

The formatted HTML anchor as a QString.

---

function makePrompLink [2/2]

Creates an HTML link that triggers an AI prompt with the given text.

static QString SBGUIHtmlFilter::makePrompLink (
    const QString & prompt,
    const QString & displayName="Ask SAMSON AI"
) 

<a href="ai://?action=ENC(prompt)" LINK_STYLE>Ask SAMSON AI</a>

The link uses the custom "ai://" scheme with the prompt percent‑encoded as a query parameter.

Parameters:

• prompt The prompt text to encode in the link.
• displayName Text displayed for the hyperlink.

Returns:

The formatted HTML anchor as a QString.

---

function makeUrlLink

Constructs an HTML anchor element linking to a URL, optionally with UTM parameters.

static QString SBGUIHtmlFilter::makeUrlLink (
    const QUrl & url,
    const QString & displayName,
    const QString & utm_content,
    const QString & utm_source=QStringLiteral("SAMSON")
) 

<a href="URL" LINK_STYLE>displayName</a>

The function ensures the URL includes the provided UTM source and content values, then returns a formatted tag with the display name escaped for HTML.

Parameters:

• url Base URL for the link.
• displayName Text displayed for the hyperlink.
• utm_content Optional UTM content parameter; if empty, the parameter is omitted.
• utm_source Optional UTM source parameter; defaults to "SAMSON".

Returns:

The complete HTML anchor as a QString.

---

function setHoverHandler

Sets the global handler invoked when a hyperlink is hovered.

static void SBGUIHtmlFilter::setHoverHandler (
    LinkHoverHandler handler
) 

The provided callable receives the href string of the hovered link. Passing an empty handler disables custom hover handling.

Parameters:

• handler Callable to handle link hover events.

---

function setLinkHandler

Set global handlers.

static void SBGUIHtmlFilter::setLinkHandler (
    LinkHandler handler
) 

Sets the global handler invoked when a hyperlink is activated.

The provided callable receives the href string of the activated link. Passing an empty handler disables custom link activation handling.

Parameters:

• handler Callable to handle link activation events.

---

function wireLabel

Wire a single QLabel explicitly.

static void SBGUIHtmlFilter::wireLabel (
    QLabel * label
) 

Wires a QLabel to route hyperlink clicks and hover events through the global handlers.

The function configures the label to emit linkActivated and linkHovered signals, disables automatic opening of external links, and updates the cursor on hover.

Parameters:

• label Pointer to the QLabel to wire.

---

function wireTextBrowser

Wire a single QTextBrowser explicitly.

static void SBGUIHtmlFilter::wireTextBrowser (
    QTextBrowser * browser
) 

Wires a QTextBrowser to route hyperlink clicks and hover events through the global handlers.

The function disables automatic link navigation and external link opening, and connects the anchorClicked and highlighted signals to the appropriate handlers.

Parameters:

• browser Pointer to the QTextBrowser to wire.

---

function wireTextEdit

Wire a single QTextEdit explicitly (adds a viewport event filter).

static void SBGUIHtmlFilter::wireTextEdit (
    QTextEdit * edit
) 

Wires a QTextEdit by installing a viewport event filter to detect hyperlink interaction.

The function enables mouse tracking on the edit and its viewport, and installs a TextEditViewportFilter instance to handle link hover and activation.

Parameters:

• edit Pointer to the QTextEdit to wire.

---