Skip to main content
The Browser library provides web rendering capabilities for displaying documentation, handling navigation, and enabling JavaScript communication between C++ and web content.

​
Architecture Overview

The browser component is built on Qt WebEngine (Chromium):

​
Browser::WebView

Custom web view widget extending QWebEngineView with Zeal-specific functionality. Location: src/libs/browser/webview.h

​
Interface

class WebView final : public QWebEngineView
{
public:
    explicit WebView(QWidget *parent = nullptr);
    
    // Zoom management
    int zoomLevel() const;
    void setZoomLevel(int level);
    static const QVector<int> &availableZoomLevels();
    static int defaultZoomLevel();
    
    bool eventFilter(QObject *watched, QEvent *event) override;
    
public slots:
    void zoomIn();
    void zoomOut();
    void resetZoom();
    
signals:
    void zoomLevelChanged();
    
protected:
    QWebEngineView *createWindow(QWebEnginePage::WebWindowType type) override;
    void contextMenuEvent(QContextMenuEvent *event) override;
};

​
Key Features

​
Zoom Control

From src/libs/browser/webview.h:20-31: 
int zoomLevel() const;
void setZoomLevel(int level);
static const QVector<int> &availableZoomLevels();
static int defaultZoomLevel();

public slots:
    void zoomIn();
    void zoomOut();
    void resetZoom();
Provides discrete zoom levels for consistent documentation reading experience.

​
Event Handling

From src/libs/browser/webview.h:41-42: 
bool handleMouseReleaseEvent(QMouseEvent *event);
bool handleWheelEvent(QWheelEvent *event);
Custom event handling for:
  • Mouse events: Middle-click for opening links in new tabs
  • Wheel events: Ctrl+Wheel for zooming

​
Context Menu

From src/libs/browser/webview.h:44-46: 
QMenu *m_contextMenu = nullptr;
QUrl m_clickedLink;
int m_zoomLevel = 0;
Custom context menu with Zeal-specific actions:
  • Open link in new tab
  • Copy link address
  • Inspect element (in debug builds)

​
Window Creation

QWebEngineView *createWindow(QWebEnginePage::WebWindowType type) override;
Handles requests to open new windows/tabs from JavaScript or link targets.

​
Browser::WebPage

Custom web page implementation with navigation control and JavaScript integration. Location: src/libs/browser/webpage.h

​
Interface

class WebPage final : public QWebEnginePage
{
public:
    explicit WebPage(QObject *parent = nullptr);
    
protected:
    bool acceptNavigationRequest(const QUrl &requestUrl, 
                                 NavigationType type, 
                                 bool isMainFrame) override;
    void javaScriptConsoleMessage(QWebEnginePage::JavaScriptConsoleMessageLevel level,
                                  const QString &message,
                                  int lineNumber,
                                  const QString &sourceId) override;
};
From src/libs/browser/webpage.h:21: 
bool acceptNavigationRequest(const QUrl &requestUrl, 
                             NavigationType type, 
                             bool isMainFrame) override;
Controls which navigation requests are allowed:
  • Local documentation: Always allowed
  • External links: Subject to user preference (Settings::ExternalLinkPolicy)
  • JavaScript navigation: Validated before execution

​
JavaScript Console

From src/libs/browser/webpage.h:22: 
void javaScriptConsoleMessage(QWebEnginePage::JavaScriptConsoleMessageLevel level,
                              const QString &message,
                              int lineNumber,
                              const QString &sourceId) override;
Captures JavaScript console messages for debugging and error reporting.

​
Browser::WebBridge

Bridge between C++ code and JavaScript in web pages. Location: src/libs/browser/webbridge.h

​
Interface

class WebBridge final : public QObject
{
    Q_OBJECT
    Q_DISABLE_COPY_MOVE(WebBridge)
    Q_PROPERTY(QString AppVersion READ appVersion CONSTANT)
public:
    explicit WebBridge(QObject *parent = nullptr);
    
signals:
    void actionTriggered(const QString &action);
    
public slots:
    Q_INVOKABLE void openShortUrl(const QString &key);
    Q_INVOKABLE void triggerAction(const QString &action);
    
private:
    QString appVersion() const;
};

​
JavaScript Integration

The WebBridge is exposed to JavaScript through Qt’s WebChannel mechanism.

​
From JavaScript

// Access from JavaScript (when WebChannel is set up)
window.zeal.openShortUrl('key');
window.zeal.triggerAction('action-name');

// Read properties
console.log(window.zeal.AppVersion);

​
Q_INVOKABLE Methods

From src/libs/browser/webbridge.h:24-25: 
Q_INVOKABLE void openShortUrl(const QString &key);
Q_INVOKABLE void triggerAction(const QString &action);
These methods can be called directly from JavaScript:
  • openShortUrl: Opens documentation using short URL keys
  • triggerAction: Triggers application actions from web content

​
Properties

From src/libs/browser/webbridge.h:16: 
Q_PROPERTY(QString AppVersion READ appVersion CONSTANT)
Exposes application version to JavaScript for feature detection.

​
Signals

From src/libs/browser/webbridge.h:21: 
signals:
    void actionTriggered(const QString &action);
Emitted when JavaScript requests an action, allowing the main application to respond.

​
Browser::UrlRequestInterceptor

Intercepts and modifies URL requests before they’re sent. Location: src/libs/browser/urlrequestinterceptor.h

​
Interface

class UrlRequestInterceptor final : public QWebEngineUrlRequestInterceptor
{
public:
    UrlRequestInterceptor(QObject *parent = nullptr);
    void interceptRequest(QWebEngineUrlRequestInfo &info) override;
    
private:
    void blockRequest(QWebEngineUrlRequestInfo &info);
};

​
Request Interception

From src/libs/browser/urlrequestinterceptor.h:19: 
void interceptRequest(QWebEngineUrlRequestInfo &info) override;
Interception enables:
  • Blocking unwanted requests: Ads, tracking, external resources
  • URL rewriting: Redirecting to local HTTP server
  • Security controls: Preventing unauthorized access
  • Resource optimization: Blocking unnecessary assets

​
Use Cases

  1. Local Documentation Serving
  2. Privacy Protection
    • Block external tracking scripts
    • Prevent analytics beacons
  3. Resource Control
    • Block large unnecessary resources
    • Optimize page load times

​
WebEngine Integration

​
Profile Management

Zeal uses Qt WebEngine profiles to manage:
  • Persistent storage: Cookies, cache, local storage
  • HTTP user agent: Custom user agent string
  • Request interceptor: URL filtering and rewriting

​
JavaScript Injection

Zeal can inject JavaScript into pages for:
  • Setting up WebChannel communication
  • Applying custom styling
  • Adding navigation enhancements
  • Implementing keyboard shortcuts

​
Settings

Web engine settings configured by Zeal: 
// Font settings from Core::Settings
settings()->setFontFamily(QWebEngineSettings::StandardFont, defaultFontFamily);
settings()->setFontFamily(QWebEngineSettings::SerifFont, serifFontFamily);
settings()->setFontSize(QWebEngineSettings::DefaultFontSize, defaultFontSize);

// Feature flags
settings()->setAttribute(QWebEngineSettings::JavascriptEnabled, jsEnabled);
settings()->setAttribute(QWebEngineSettings::LocalContentCanAccessRemoteUrls, false);

​
Custom CSS Support

Users can apply custom CSS to all documentation: 
// From Core::Settings
QString customCssFile;
The CSS is injected into each page to:
  • Override default documentation styling
  • Implement dark mode
  • Adjust typography
  • Hide unwanted elements

​
Search Integration

The browser component integrates with search:

​
URL Format

Documentation URLs include search terms for highlighting: 
http://localhost:port/docset/page.html#anchor?searchTerm=query

​
Highlight on Navigate

When Settings::isHighlightOnNavigateEnabled is true:
  • Search terms are extracted from URL
  • JavaScript is injected to highlight matches
  • Page scrolls to first match
WebView inherits Qt WebEngine’s history management: 
// Available through QWebEngineView
history()->back();
history()->forward();
history()->goToItem(item);
History is preserved per-tab and persists across application restarts.

​
Developer Tools

In debug builds, the web inspector is available: 
// Enable developer tools
page()->settings()->setAttribute(
    QWebEngineSettings::DeveloperExtrasEnabled, true);
Accessible via context menu “Inspect Element” option.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us