Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorControl::SearchEntry Struct Reference

One searchable item in the global settings search index. More...

#include <PhosphorControl/SearchEntry.h>

Public Types

enum class  Kind {
  Page , Section , Setting , Entity ,
  Action
}
enum class  Mode { Both , SimpleOnly , AdvancedOnly }
 Which UI mode(s) can reach this entry. More...

Public Member Functions

QString address () const
 The navigable address consumed by SettingsController::navigateTo, which splits on the FIRST '#'.

Public Attributes

Kind kind = Kind::Page
Mode mode = Mode::Both
QString pageId
 Navigation target page id (must be a registered page).
QString actionId
 App-defined command id for Kind::Action entries; empty otherwise.
QString anchor
 Optional reveal anchor within the page. Empty for a plain page target.
QString title
 Primary display label (translated).
QString subtitle
 Secondary context line — typically the breadcrumb (translated).
QString icon
 Icon name (freedesktop / Kirigami theme).
QStringList keywords
 Extra synonyms / search terms (translated). Not displayed.
bool advancedOnly = false
 True when the target row/card is only rendered in advanced mode, on a page that itself shows in BOTH modes.
QString foldedTitle
 Search-folded copies of the matched fields, filled by SearchRanker::prefold.
QString foldedSubtitle
QStringList foldedKeywords

Detailed Description

One searchable item in the global settings search index.

Pack-agnostic: a settings app populates these from its page registry (kind Page), its authored anchor catalog (kind Section / Setting), and its dynamic content providers (kind Entity). The ranker scores a query against title / keywords / subtitle; activating a result navigates to address() ("pageId" or "pageId#anchor") via SettingsController::navigateTo.

All user-facing strings (title / subtitle / keywords) must be translated by the producer — the index stores them verbatim.

Member Enumeration Documentation

◆ Kind

Enumerator
Page 

A navigable settings page.

Section 

A card / section within a page (anchor).

Setting 

An individual setting row within a page (anchor).

Entity 

A dynamic content item (rule, shader, layout, …).

Action 

An app-level command rather than a destination (open an overlay, start a wizard).

Carries actionId instead of a page address; the app's search UI dispatches it (GlobalSearchField emits actionTriggered) instead of navigating. Appended last so the integer values QML sees for the existing kinds are stable.

◆ Mode

Which UI mode(s) can reach this entry.

COMPUTED by SearchController::buildIndex from the host page's registry tier ANDed with the entry's own advancedOnly flag — producers never set it. The index carries every entry regardless of the live mode; this tag is what the results surface exposes so the UI can badge a mode-specific result and switch the mode before navigating to it.

Enumerator
Both 

Reachable in simple and advanced mode alike.

SimpleOnly 

Lives on a SimpleOnly page (a condensed simple surface).

AdvancedOnly 

On an AdvancedOnly page, or an advanced-gated row.

Member Function Documentation

◆ address()

QString PhosphorControl::SearchEntry::address ( ) const
inline

The navigable address consumed by SettingsController::navigateTo, which splits on the FIRST '#'.

Page ids must therefore not contain '#' (they are registry identifiers, which never do); the anchor may.

Member Data Documentation

◆ actionId

QString PhosphorControl::SearchEntry::actionId

App-defined command id for Kind::Action entries; empty otherwise.

The producer and the app's action dispatcher share this vocabulary — the library never interprets it.

◆ advancedOnly

bool PhosphorControl::SearchEntry::advancedOnly = false

True when the target row/card is only rendered in advanced mode, on a page that itself shows in BOTH modes.

The registry's page-level tier cannot express this: the host page shows in simple mode too, so without this flag the entry would classify as Mode::Both and a simple-mode activation would reveal a collapsed row instead of switching to advanced first. Producers set it to mirror the row's own advanced-only declaration.

◆ anchor

QString PhosphorControl::SearchEntry::anchor

Optional reveal anchor within the page. Empty for a plain page target.

◆ foldedKeywords

QStringList PhosphorControl::SearchEntry::foldedKeywords

◆ foldedSubtitle

QString PhosphorControl::SearchEntry::foldedSubtitle

◆ foldedTitle

QString PhosphorControl::SearchEntry::foldedTitle

Search-folded copies of the matched fields, filled by SearchRanker::prefold.

EMPTY means "not prefolded" and the ranker folds on the fly, so an entry built without prefolding still matches correctly, just slower.

These exist because folding is the ranker's dominant cost: matching one entry folds its title, its subtitle and every keyword, so a keystroke over a ~350-entry catalogue averaging ~4 keywords ran ~2000 Unicode NFD walks. The index is already cached behind a dirty flag, so that work was being repeated on immutable data.

◆ icon

QString PhosphorControl::SearchEntry::icon

Icon name (freedesktop / Kirigami theme).

◆ keywords

QStringList PhosphorControl::SearchEntry::keywords

Extra synonyms / search terms (translated). Not displayed.

◆ kind

Kind PhosphorControl::SearchEntry::kind = Kind::Page

◆ mode

Mode PhosphorControl::SearchEntry::mode = Mode::Both

◆ pageId

QString PhosphorControl::SearchEntry::pageId

Navigation target page id (must be a registered page).

Empty for Kind::Action entries.

◆ subtitle

QString PhosphorControl::SearchEntry::subtitle

Secondary context line — typically the breadcrumb (translated).

◆ title

QString PhosphorControl::SearchEntry::title

Primary display label (translated).


The documentation for this struct was generated from the following file: