Overview

The HUD consists of the interface in the shell and a backend service, hud-service. This document attempts to describe the internal architecture of the service.

The most important type in the service is HudSource. This is an interface. Each source is an entity against which a search can be performed. There is one interface method: hud_source_search(). This is the main mechanism by which queries are performed in the HUD. The interface also features a signal ::changed that is emitted when the result of searching may have changed.

Several implementations of HudSource exist. A particular type of source that gathers possible search results is referred to as a "collector". There are two of these: HudMenuModelCollector (for GDBusMenuModel) and HudDbusmenuCollector for Dbusmenu. These "collector" sources only function when targetted at a particular endpoint (ie: a unique name and object path on D-Bus). This is only useful for searching for items in one particular set of menus.

HudWindowSource acts as a multiplexer. It is responsible for determining the currently focused window and performing searches submitted to it against the correct collector for that window. Similarly, there are HudIndicatorSource and HudAppIndicatorSource for performing searches against the system and application indicators, respectively.

Finally, there is HudSourceList which functions as a list of multiple other HudSources (such that performing a search against the list gives the combined result of searches performed against each of the contained sources).

The hud-service initialises itself by creating the window, indicator and appindicator sources and putting each of them into a HudSourceList. This is the source against which all queries submitted to the service are executed.

Collectors are essentially a collection of HudItems. Each item corresponds to an action that may appear in the results of a search made with the HUD. Items have a list of strings describing themselves (eg: ['File', 'Open'] or ['Bluetooth', 'Settings...']) and some information about their origin (eg: the desktop file of the application or indicator that created them). An item can be disabled, in which case it will never appear in the results of a search. Items are activated using hud_item_activate() which is implemented by the collector in the appropriate way.

The result of performing a search is a set of HudResults. Each result refers to HudItem along with information about why that item matched, and how closely.

The toplevel interface to performing a query is HudQuery. It takes a search string and a reference to a HudSource to search (which, as implemented, is always the toplevel 'list' source). It submits the search to the source then sorts the results by relevence. If the source changes, it resubmits the search. The interface of HudQuery is an ordered sequence of results. HudQuery has its own ::changed signal.

hud-service is essentially a simple D-Bus interface corresponding to HudQuery as used against the toplevel source list. New queries can be created using StartQuery. Queries can be destroyed using CloseQuery. HudItems corresponding to results from the query can be activated using ExecuteQuery. Finally, the ::changed signal is reported as the UpdatedQuery D-Bus signal.