UI Component

The UI library provides the graphical user interface for Zeal, built entirely with Qt Widgets for native look and feel across platforms.

Component Hierarchy

WidgetUi::MainWindow

The main application window managing tabs, search, and navigation. Location: src/libs/ui/mainwindow.h

Interface

class MainWindow : public QMainWindow
{
public:
    explicit MainWindow(Core::Application *app, QWidget *parent = nullptr);
    
    void search(const Registry::SearchQuery &query);
    void bringToFront();
    BrowserTab *createTab();
    
public slots:
    void toggleWindow();
    
signals:
    void currentTabChanged();
    
protected:
    void changeEvent(QEvent *event) override;
    void closeEvent(QCloseEvent *event) override;
    bool eventFilter(QObject *object, QEvent *event) override;
    void keyPressEvent(QKeyEvent *keyEvent) override;
};

Member Components

From src/libs/ui/mainwindow.h:82-105:

Core::Application *m_application = nullptr;
Core::Settings *m_settings = nullptr;
Browser::WebBridge *m_webBridge = nullptr;

QxtGlobalShortcut *m_globalShortcut = nullptr;

QMenuBar *m_menuBar = nullptr;
QTabBar *m_tabBar = nullptr;

QSplitter *m_splitter = nullptr;
QStackedWidget *m_webViewStack = nullptr;

// Actions
QAction *m_quitAction = nullptr;
QAction *m_showDocsetManagerAction = nullptr;
QAction *m_showPreferencesAction = nullptr;
#ifndef Q_OS_MACOS
QAction *m_showMenuBarAction = nullptr;
#endif

QSystemTrayIcon *m_trayIcon = nullptr;

Tab Management

From src/libs/ui/mainwindow.h:64-75:

private slots:
    void closeTab(int index = -1);
    void moveTab(int from, int to);
    void duplicateTab(int index);
    
private:
    void addTab(BrowserTab *tab, int index = -1);
    BrowserTab *currentTab() const;
    BrowserTab *tabAt(int index) const;

Supports:

Multiple tabs: Each with independent browsing history
Tab reordering: Drag and drop support
Tab duplication: Copy current tab state
Tab closing: With confirmation for multiple tabs

Layout Structure

QMenuBar (m_menuBar): Top menu bar (hidden on macOS by default)
QTabBar (m_tabBar): Tab switcher
QSplitter (m_splitter): Resizable split between sidebar and content
- Left: SearchSidebar
- Right: QStackedWidget with BrowserTabs

Window State

Window geometry and splitter positions are persisted:

// From Core::Settings
QByteArray windowGeometry;
QByteArray verticalSplitterGeometry;
QByteArray tocSplitterState;

Restored on application startup for consistent user experience.

Global Shortcuts

From src/libs/ui/mainwindow.h:87:

QxtGlobalShortcut *m_globalShortcut = nullptr;

Enables system-wide keyboard shortcut to show/hide Zeal, even when the application is minimized or hidden.

System Tray Integration

From src/libs/ui/mainwindow.h:77-78,105:

void createTrayIcon();
void removeTrayIcon();
QSystemTrayIcon *m_trayIcon = nullptr;

Provides:

Tray icon with menu
Minimize to tray option
Quick access to search
Application state indicator

WidgetUi::SearchSidebar

Search interface with results display and table of contents. Location: src/libs/ui/searchsidebar.h

Interface

class SearchSidebar final : public Sidebar::View
{
public:
    explicit SearchSidebar(QWidget *parent = nullptr);
    SearchSidebar *clone(QWidget *parent = nullptr) const;
    
    Registry::SearchModel *pageTocModel() const;
    
signals:
    void activated();
    void navigationRequested(const QUrl &url);
    
public slots:
    void focusSearchEdit(bool clear = false);
    void search(const Registry::SearchQuery &query);
};

Components

From src/libs/ui/searchsidebar.h:61-75:

SearchEdit *m_searchEdit = nullptr;
bool m_pendingSearchEditFocus = false;

// Index and search results tree view
QTreeView *m_treeView = nullptr;
QModelIndexList m_expandedIndexList;
int m_pendingVerticalPosition = 0;
Registry::SearchModel *m_searchModel = nullptr;

// TOC list view
QListView *m_pageTocView = nullptr;
Registry::SearchModel *m_pageTocModel = nullptr;

QSplitter *m_splitter = nullptr;
QTimer *m_delayedNavigationTimer = nullptr;

Layout

┌─────────────────────────┐
│   [Search Input]        │
├─────────────────────────┤
│                         │
│   QTreeView             │
│   (Search Results)      │
│                         │
├─────────────────────────┤ ← QSplitter
│   QListView             │
│   (Page TOC)            │
└─────────────────────────┘

Search Edit

Custom search input widget with:

Auto-completion using docset keywords
Query syntax hints
Search history
Clear button

Results Tree View

Displays search results in a tree structure:

Grouped by docset
Expandable/collapsible groups
Custom delegate for rich rendering
Keyboard navigation support

Shows current page TOC:

Extracted from page structure
Click to jump to section
Updates automatically on navigation
Collapsible via splitter

From src/libs/ui/searchsidebar.h:75:

QTimer *m_delayedNavigationTimer = nullptr;

Implements delayed navigation when using keyboard:

Arrow keys browse results without navigating
Timer triggers navigation after brief pause
Reduces unnecessary page loads
Improves keyboard navigation experience

WidgetUi::SettingsDialog

Configuration interface for all application settings. Location: src/libs/ui/settingsdialog.h

Interface

class SettingsDialog : public QDialog
{
public:
    explicit SettingsDialog(QWidget *parent = nullptr);
    
public slots:
    void chooseCustomCssFile();
    void chooseDocsetStoragePath();
    
private:
    void loadSettings();
    void saveSettings();
    
private:
    Ui::SettingsDialog *ui = nullptr;
};

Settings Categories

The dialog uses a tabbed interface with categories:

General
- Startup behavior
- System tray options
- Global shortcuts
- Update checking
Search
- Fuzzy search toggle
- Docset path configuration
Content
- Font configuration
- Appearance (light/dark/auto)
- Custom CSS file
- External link policy
- Smooth scrolling
- Highlight on navigate
Network
- Proxy configuration
- SSL error handling

UI Definition

The dialog uses Qt Designer UI file:

settingsdialog.ui: Visual layout definition
Ui::SettingsDialog: Generated UI class

Allows rapid iteration on interface design without code changes.

WidgetUi::DocsetsDialog

Docset management and download interface. Location: src/libs/ui/docsetsdialog.h

Interface

class DocsetsDialog : public QDialog
{
public:
    explicit DocsetsDialog(Core::Application *app, QWidget *parent = nullptr);
    
private slots:
    void addDashFeed();
    void updateSelectedDocsets();
    void updateAllDocsets();
    void removeSelectedDocsets();
    void updateDocsetFilter(const QString &filterString);
    void downloadSelectedDocsets();
    void downloadCompleted();
    void downloadProgress(qint64 received, qint64 total);
    void extractionCompleted(const QString &filePath);
    void extractionError(const QString &filePath, const QString &errorString);
    void extractionProgress(const QString &filePath, qint64 extracted, qint64 total);
    void loadDocsetList();
};

Tabs

Installed Tab

Lists installed docsets
Shows version and size
Update indicator
Remove button
Bulk update option

Available Tab

Lists all available docsets
Search/filter functionality
Download button
Version information
Download progress

Data Management

From src/libs/ui/docsetsdialog.h:77-81:

Util::CaseInsensitiveMap<Registry::DocsetMetadata> m_availableDocsets;
QMap<QString, Registry::DocsetMetadata> m_userFeeds;
QHash<QString, QTemporaryFile *> m_tmpFiles;

m_availableDocsets: Downloaded from zealdocs.org
m_userFeeds: User-added Dash feeds
m_tmpFiles: Temporary files during download

Download Management

From src/libs/ui/docsetsdialog.h:75,92-93:

QList<QNetworkReply *> m_replies;
void cancelDownloads();
QNetworkReply *download(const QUrl &url);

Supports:

Multiple concurrent downloads
Progress tracking per docset
Cancellation support
Automatic extraction after download

Custom Delegates

SearchItemDelegate

Location: src/libs/ui/searchitemdelegate.h Custom item delegate for search results:

Symbol type icon
Symbol name with match highlighting
Docset name badge
Custom colors and fonts

DocsetListItemDelegate

Location: src/libs/ui/docsetlistitemdelegate.h Custom item delegate for docset lists:

Docset icon
Name and description
Version information
Update indicator
Download progress bar

BrowserTab

Location: src/libs/ui/browsertab.h Container for a browser view with additional UI:

class BrowserTab final : public QWidget
{
public:
    explicit BrowserTab(Browser::WebBridge *webBridge, QWidget *parent = nullptr);
    
    Browser::WebView *webView() const;
    // Additional tab-specific functionality
};

Contains:

WebView widget
Search toolbar (find in page)
Loading indicator

SidebarViewProvider

Location: src/libs/ui/sidebarviewprovider.h Provides sidebar views for tab system:

class SidebarViewProvider : public QObject
{
public:
    explicit SidebarViewProvider(MainWindow *mainWindow, QObject *parent = nullptr);
    // Creates and manages sidebar views per tab
};

Each tab can have its own sidebar state (search results, TOC, etc.).

Qt Widgets Usage

Zeal uses Qt Widgets extensively:

QMainWindow: Application window with dock, menu, status bar support
QSplitter: Resizable panes
QTabBar: Tab management
QTreeView/QListView: Model-view architecture for data display
QDialog: Modal dialogs
QMenu/QMenuBar: Application menus
QAction: User actions with shortcuts
QSystemTrayIcon: System tray integration

Extensive keyboard support throughout:

Ctrl+K / Cmd+K: Focus search
Ctrl+T / Cmd+T: New tab
Ctrl+W / Cmd+W: Close tab
Alt+Left/Right: Navigate history
Ctrl+F / Cmd+F: Find in page
Esc: Clear search, close dialogs
Custom shortcuts configurable in settings

Accessibility

Qt Widgets provide built-in accessibility:

Screen reader support through Qt Accessibility API
Keyboard navigation for all functions
Focus indicators
Tooltips and status messages

Platform Integration

macOS

Native menu bar integration
Dock icon with menu
Native dialogs for file selection

Windows

Taskbar integration
Jump list support
Native file dialogs

Linux

Desktop environment integration
System tray support
Standard dialogs

Building

Architecture

Contributing

Documentation Index

​Component Hierarchy

​WidgetUi::MainWindow

​Interface

​Member Components

​Tab Management

​Layout Structure

​Window State

​Global Shortcuts

​System Tray Integration

​WidgetUi::SearchSidebar

​Interface

​Components

​Layout

​Search Edit

​Results Tree View

​Table of Contents

​Delayed Navigation

​WidgetUi::SettingsDialog

​Interface

​Settings Categories

​UI Definition

​WidgetUi::DocsetsDialog

​Interface

​Tabs

​Installed Tab

​Available Tab

​Data Management

​Download Management

​Custom Delegates

​SearchItemDelegate

​DocsetListItemDelegate

​BrowserTab

​SidebarViewProvider

​Qt Widgets Usage

​Keyboard Navigation

​Accessibility

​Platform Integration

​macOS

​Windows

​Linux

​See Also

Component Hierarchy

WidgetUi::MainWindow

Interface

Member Components

Tab Management

Layout Structure

Window State

Global Shortcuts

System Tray Integration

WidgetUi::SearchSidebar

Interface

Components

Layout

Search Edit

Results Tree View

Table of Contents

Delayed Navigation

WidgetUi::SettingsDialog

Interface

Settings Categories

UI Definition

WidgetUi::DocsetsDialog

Interface

Tabs

Installed Tab

Available Tab

Data Management

Download Management

Custom Delegates

SearchItemDelegate

DocsetListItemDelegate

BrowserTab

SidebarViewProvider

Qt Widgets Usage

Keyboard Navigation

Accessibility

Platform Integration

macOS

Windows

Linux

See Also