← Back to branch summary

~ubuntu-branches/ubuntu/vivid/indicator-appmenu/vivid-proposed

« back to all changes in this revision

Viewing changes to docs/devel/hud-overview.xml

  • Committer: Package Import Robot
  • Author(s): Automatic PS uploader, Mathieu Trudel-Lapierre, Didier Roche, Automatic PS uploader
  • Date: 2012-11-23 07:39:58 UTC
  • mfrom: (1.1.35)
  • Revision ID: package-import@ubuntu.com-20121123073958-rr5gz4chpdjfmafa
Tags: 12.10.4daily12.11.23-0ubuntu1
https://launchpad.net/bugs/773101
https://launchpad.net/bugs/773101
[ Mathieu Trudel-Lapierre ]
* debian/control:
  - Reorganize Build-Depends for clarity.
  - Adjust style to be consistent with other indicator packages.
  - Drop Build-Depends on cdbs.
  - Bump debhelper Build-Depends to (>= 9). 
  - Add gnome-common to Build-Depends.
  - Update Vcs-Bzr, Vcs-Browser and add notice to uploaders.
  - Add gtk-doc-tools to Build-Depends.
* debian/compat: bump compat level to 9.
* debian/rules:
  - Convert to using the dh sequencer.
  - Make sure the build fails if there are files not listed in install files
    when building the packages.
  - Override dh_autoreconf to call autogen.sh and not run configure.
  - Temporarily disable tests due to missing dependencies.
* debian/indicator-appmenu.install,
  debian/indicator-appmenu-tools.install: update paths to install private
  binaries to the /usr/lib/<triplet> paths.

[ Didier Roche ]
* Automatic snapshot from revision 219 (bootstrap):
  - Adds childless menu support to the Unity menu panel. (LP: #773101)
  - add pot template
* Unity global menu bar hides childless menu items (LP: #773101)

[ Automatic PS uploader ]
* Automatic snapshot from revision 221

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/devel/hud-overview.xml
 
1
<?xml version='1.0'?>
 
2
 
 
3
 
 
4
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
 
5
  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
 
6
 
 
7
<chapter>
 
8
  <title>Overview</title>
 
9
 
 
10
  <para>
 
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.
 
13
  </para>
 
14
 
 
15
  <para>
 
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.
 
22
  </para>
 
23
 
 
24
  <para>
 
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.
 
32
  </para>
 
33
 
 
34
  <para>
 
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.
 
41
  </para>
 
42
 
 
43
  <para>
 
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).
 
47
  </para>
 
48
 
 
49
  <para>
 
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.
 
53
  </para>
 
54
 
 
55
  <para>
 
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.
 
64
  </para>
 
65
 
 
66
  <para>
 
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.
 
70
  </para>
 
71
 
 
72
  <para>
 
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.
 
80
  </para>
 
81
 
 
82
  <para>
 
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.
 
90
  </para>
 
91
</chapter>