4
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
5
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
8
<title>Overview</title>
11
The HUD consists of the interface in the shell and a backend service, <literal>hud-service</literal>. This
12
document attempts to describe the internal architecture of the service.
16
The most important type in the service is <link linkend="HudSource"><type>HudSource</type></link>. This is
17
an interface. Each source is an entity against which a search can be performed. There is one interface
18
method: <link linkend="hud-source-search"><function>hud_source_search()</function></link>. This is the main
19
mechanism by which queries are performed in the HUD. The interface also features a signal
20
<link linkend="HudSource-changed"><function>::changed</function></link> that is emitted when the result of
21
searching may have changed.
25
Several implementations of <link linkend="HudSource"><type>HudSource</type></link> exist. A particular type
26
of source that gathers possible search results is referred to as a "collector". There are two of these:
27
<link linkend="HudMenuModelCollector"><type>HudMenuModelCollector</type></link> (for
28
<link linkend="GDBusMenuModel"><type>GDBusMenuModel</type></link>) and
29
<link linkend="HudDbusmenuCollector"><type>HudDbusmenuCollector</type></link> for Dbusmenu. These
30
"collector" sources only function when targetted at a particular endpoint (ie: a unique name and object path
31
on D-Bus). This is only useful for searching for items in one particular set of menus.
35
<link linkend="HudSourceList"><type>HudWindowSource</type></link> acts as a multiplexer. It is responsible
36
for determining the currently focused window and performing searches submitted to it against the correct
37
collector for that window. Similarly, there are
38
<link linkend="HudSourceList"><type>HudIndicatorSource</type></link> and
39
<link linkend="HudSourceList"><type>HudAppIndicatorSource</type></link> for performing searches against the
40
system and application indicators, respectively.
44
Finally, there is <link linkend="HudSourceList"><type>HudSourceList</type></link> which functions as a list
45
of multiple other <link linkend="HudSource"><type>HudSource</type></link>s (such that performing a search
46
against the list gives the combined result of searches performed against each of the contained sources).
50
The <literal>hud-service</literal> initialises itself by creating the window, indicator and appindicator
51
sources and putting each of them into a <link linkend="HudSourceList"><type>HudSourceList</type></link>.
52
This is the source against which all queries submitted to the service are executed.
56
Collectors are essentially a collection of <link linkend="HudItem"><type>HudItem</type></link>s. Each item
57
corresponds to an action that may appear in the results of a search made with the HUD. Items have a list of
58
strings describing themselves (eg: <literal>['File', 'Open']</literal> or
59
<literal>['Bluetooth', 'Settings...']</literal>) and some information about their origin (eg: the desktop
60
file of the application or indicator that created them). An item can be disabled, in which case it will
61
never appear in the results of a search. Items are activated using
62
<link linkend="hud-item-activate"><function>hud_item_activate()</function></link> which is implemented by
63
the collector in the appropriate way.
67
The result of performing a search is a set of <link linkend="HudResult"><type>HudResult</type></link>s.
68
Each result refers to <link linkend="HudItem"><type>HudItem</type></link> along with information about why
69
that item matched, and how closely.
73
The toplevel interface to performing a query is <link linkend="HudQuery"><type>HudQuery</type></link>. It
74
takes a search string and a reference to a <link linkend="HudSource"><type>HudSource</type></link> to search
75
(which, as implemented, is always the toplevel 'list' source). It submits the search to the source then
76
sorts the results by relevence. If the source changes, it resubmits the search. The interface of
77
<link linkend="HudQuery"><type>HudQuery</type></link> is an ordered sequence of results.
78
<link linkend="HudQuery"><type>HudQuery</type></link> has its own
79
<link linkend="HudQuery-changed"><function>::changed</function></link> signal.
83
<literal>hud-service</literal> is essentially a simple D-Bus interface corresponding to
84
<link linkend="HudQuery"><type>HudQuery</type></link> as used against the toplevel source list. New queries
85
can be created using <function>StartQuery</function>. Queries can be destroyed using
86
<function>CloseQuery</function>. <link linkend="HudItem"><type>HudItem</type></link>s corresponding to
87
results from the query can be activated using <function>ExecuteQuery</function>. Finally, the
88
<link linkend="HudQuery-changed"><function>::changed</function></link> signal is reported as the
89
<function>UpdatedQuery</function> D-Bus signal.
added
removed
docs/devel/hud-overview.xml
