SearchSidebar

Overview

The SearchSidebar class (Zeal::WidgetUi::SearchSidebar) provides the search interface and docset navigation for Zeal. It inherits from Sidebar::View and displays both the docset index tree and search results. Header: src/libs/ui/searchsidebar.h Namespace: Zeal::WidgetUi

Constructor

explicit SearchSidebar(QWidget *parent = nullptr);

Creates a new search sidebar with the given parent widget. Parameters:

parent - Optional parent widget (defaults to nullptr)

Behavior:

Creates search edit widget with completions
Sets up tree view for displaying docset index and search results
Creates list view for page table of contents (TOC)
Configures keyboard shortcuts (Alt+Up/Down/PageUp/PageDown/Home/End)
Connects to docset registry for search updates
Initializes with docset index model

Reference: src/libs/ui/searchsidebar.cpp:34

Copy Constructor

explicit SearchSidebar(const SearchSidebar *other, QWidget *parent = nullptr);

Creates a clone of another search sidebar (used for tab duplication). Parameters:

other - Source sidebar to clone
parent - Optional parent widget

Behavior:

Copies search query text
Clones search model
Restores expanded items
Preserves selection state
Maintains scroll position

Reference: src/libs/ui/searchsidebar.cpp:39

Public Methods

clone

SearchSidebar *clone(QWidget *parent = nullptr) const;

Creates a copy of this sidebar for tab duplication. Parameters:

parent - Optional parent widget for the clone

Returns: Pointer to the new SearchSidebar instance Reference: src/libs/ui/searchsidebar.cpp:277

pageTocModel

Registry::SearchModel *pageTocModel() const;

Returns the search model used for the page table of contents. Returns: Pointer to the page TOC SearchModel Usage: The returned model is used by browser tabs to populate the TOC with the current page’s headings. Reference: src/libs/ui/searchsidebar.cpp:282

Signals

activated

void activated();

Emitted when the user activates a search result (e.g., presses Enter or double-clicks).

navigationRequested

void navigationRequested(const QUrl &url);

Emitted when the user selects a documentation entry. Parameters:

url - URL of the documentation page to navigate to

Public Slots

focusSearchEdit

void focusSearchEdit(bool clear = false);

Focuses the search input field. Parameters:

clear - If true, clears the current search query

Behavior:

If sidebar is not visible, sets a pending focus flag to focus when shown
Otherwise, immediately focuses the search edit
Optionally clears the query text

Reference: src/libs/ui/searchsidebar.cpp:287

search

void search(const Registry::SearchQuery &query);

Performs a search with the given query. Parameters:

query - Search query to execute

Behavior:

Converts query to string and sets it in the search edit
Triggers search through the text changed signal

Reference: src/libs/ui/searchsidebar.cpp:301

Private Slots

navigateToIndex

void navigateToIndex(const QModelIndex &index);

Navigates to the documentation entry at the given model index. Parameters:

index - Model index of the entry to navigate to

Behavior:

Cancels any pending delayed navigation
Extracts URL from model index data
Emits navigationRequested signal

Reference: src/libs/ui/searchsidebar.cpp:307

navigateToIndexAndActivate

void navigateToIndexAndActivate(const QModelIndex &index);

Navigates to an entry and emits the activated signal. Parameters:

index - Model index of the entry

Behavior:

Emits navigationRequested with the entry URL
Emits activated signal

Usage: Called when user double-clicks or presses Enter on an entry. Reference: src/libs/ui/searchsidebar.cpp:323

navigateToSelectionWithDelay

void navigateToSelectionWithDelay(const QItemSelection &selection);

Schedules delayed navigation to the selected entry. Parameters:

selection - New selection

Behavior:

Stores the selected index
Starts a 400ms timer before navigating
Allows user to continue typing without interrupting with navigation

Reference: src/libs/ui/searchsidebar.cpp:334

setupSearchBoxCompletions

void setupSearchBoxCompletions();

Configures auto-completion for the search box with docset keywords. Behavior:

Collects first keyword from each loaded docset
Adds colon suffix (e.g., “qt:”, “python:”)
Enables scoped search by docset

Reference: src/libs/ui/searchsidebar.cpp:344

Protected Methods

eventFilter

bool eventFilter(QObject *object, QEvent *event) override;

Filters keyboard events from the search edit. Keyboard Handling:

Enter/Return: Emits activated signal
Arrow keys, Page Up/Down, Home/End: Forwarded to tree view
- Left/Right only forwarded when search edit is empty

Reference: src/libs/ui/searchsidebar.cpp:362

showEvent

void showEvent(QShowEvent *event) override;

Handles sidebar show events. Behavior:

Restores scroll position if pending
Focuses search edit if pending focus flag is set

Reference: src/libs/ui/searchsidebar.cpp:391

UI Components

Search Edit

Custom SearchEdit widget with auto-completion
Supports docset scoping (e.g., “qt:qwidget”)
Provides instant search as user types
Keyboard navigation integration

Tree View

Displays either:

Docset index: When search edit is empty
- Hierarchical tree structure
- Root items are docsets
- Children are documentation entries
Search results: When search query is present
- Flat list grouped by relevance
- Highlighted search matches

Features:

Custom SearchItemDelegate for styling
Preserves expanded state across searches
Uniform row heights for performance

Reference: src/libs/ui/searchsidebar.cpp:43

Page TOC View

Separate list view for table of contents
Displays headings from current page
Hidden when TOC is empty
Positioned below tree view in vertical splitter

Reference: src/libs/ui/searchsidebar.cpp:88

Splitter

Vertical splitter between tree view and TOC view
Saves/restores state in application settings
Allows user to resize TOC height

Reference: src/libs/ui/searchsidebar.cpp:186

Search Behavior

Instant Search

Search is triggered automatically as the user types:

connect(m_searchEdit, &QLineEdit::textChanged, this, [this](const QString &text) {
    if (text.isEmpty()) {
        // Show docset index
        setTreeViewModel(Core::Application::instance()->docsetRegistry()->model(), true);
    } else {
        // Show search results
        setTreeViewModel(m_searchModel, false);
    }
    Core::Application::instance()->docsetRegistry()->search(text);
});

Reference: src/libs/ui/searchsidebar.cpp:150 Navigation to selected results is delayed by 400ms to avoid interrupting the user while typing:

m_delayedNavigationTimer->setInterval(400);
m_delayedNavigationTimer->setSingleShot(true);

Reference: src/libs/ui/searchsidebar.cpp:202

Search Result Updates

Connects to docset registry search completion:

connect(registry, &DocsetRegistry::searchCompleted,
        this, [this](const QList<Registry::SearchResult> &results) {
    m_delayedNavigationTimer->stop();
    m_searchModel->setResults(results);
    
    // Auto-select first result
    const QModelIndex index = m_searchModel->index(0, 0, QModelIndex());
    m_treeView->setCurrentIndex(index);
    m_delayedNavigationTimer->setProperty("index", index);
    m_delayedNavigationTimer->start();
});

Reference: src/libs/ui/searchsidebar.cpp:216

Integration with DocsetRegistry

The sidebar integrates tightly with Registry::DocsetRegistry:

Search Execution

Search queries are forwarded to the registry:

Core::Application::instance()->docsetRegistry()->search(text);

Docset Events

Listens for docset lifecycle events:

Docset loaded: Refreshes search completions
Docset unloaded: Removes results from that docset, refreshes completions

Reference: src/libs/ui/searchsidebar.cpp:232

Search Model

Uses Registry::SearchModel to manage search results:

Receives results from registry
Provides model interface for tree view
Supports filtering by docset name

Keyboard Shortcuts

Allows navigating the tree view while focused on search edit:

Alt+Up/Down: Move selection up/down
Alt+PageUp/PageDown: Jump page up/down
Alt+Home/End: Jump to first/last item

Reference: src/libs/ui/searchsidebar.cpp:75

Search Edit Keys

Enter: Activate selected result
Arrow keys: Navigate tree (when appropriate)
Escape: Clear search (handled by parent window)

State Preservation

When cloning for tab duplication, preserves:

Search query text
Expanded tree items
Current selection
Scroll position
TOC state

Reference: src/libs/ui/searchsidebar.cpp:118

Example Usage

// Create sidebar
SearchSidebar *sidebar = new SearchSidebar();

// Connect navigation signal
connect(sidebar, &SearchSidebar::navigationRequested,
        this, [](const QUrl &url) {
    // Load documentation page
    webView->load(url);
});

// Connect activation signal
connect(sidebar, &SearchSidebar::activated,
        this, []() {
    // Focus web view after activation
    webView->setFocus();
});

// Perform search
Registry::SearchQuery query("QWidget");
sidebar->search(query);

// Focus search edit
sidebar->focusSearchEdit();

Performance Considerations

Deferred Updates

When docsets are unloaded while sidebar is not visible, updates are deferred:

if (isVisible()) {
    m_treeView->setUpdatesEnabled(false);
    m_searchModel->removeSearchResultWithName(name);
    m_treeView->setUpdatesEnabled(true);
} else {
    m_searchModel->removeSearchResultWithName(name);
}

Reference: src/libs/ui/searchsidebar.cpp:233

Uniform Row Heights

Enables optimized rendering for large result sets:

m_treeView->setUniformRowHeights(true);

Core

Registry

Browser

UI

​Overview

​Constructor

​Copy Constructor

​Public Methods

​clone

​pageTocModel

​Signals

​activated

​navigationRequested

​Public Slots

​focusSearchEdit

​search

​Private Slots

​navigateToIndex

​navigateToIndexAndActivate

​navigateToSelectionWithDelay

​setupSearchBoxCompletions

​Protected Methods

​eventFilter

​showEvent

​UI Components

​Search Edit

​Tree View

​Page TOC View

​Splitter

​Search Behavior

​Instant Search

​Delayed Navigation

​Search Result Updates

​Integration with DocsetRegistry

​Search Execution

​Docset Events

​Search Model

​Keyboard Shortcuts

​Alt+Navigation Keys

​Search Edit Keys

​State Preservation

​Example Usage

​Performance Considerations

​Deferred Updates

​Uniform Row Heights

Build docs developers (and LLMs) love

Overview

Constructor

Copy Constructor

Public Methods

clone

pageTocModel

Signals

activated

navigationRequested

Public Slots

focusSearchEdit

search

Private Slots

navigateToIndex

navigateToIndexAndActivate

navigateToSelectionWithDelay

setupSearchBoxCompletions

Protected Methods

eventFilter

showEvent

UI Components

Search Edit

Tree View

Page TOC View

Splitter

Search Behavior

Instant Search

Delayed Navigation

Search Result Updates

Integration with DocsetRegistry

Search Execution

Docset Events

Search Model

Keyboard Shortcuts

Alt+Navigation Keys

Search Edit Keys

State Preservation

Example Usage

Performance Considerations

Deferred Updates

Uniform Row Heights