[Deskbar] Deskbar General UI Overview

[Mikkel Kamstrup Erlandsen <kamstrup daimi au dk>]

Hacking the Deskbar UI code is not as easy as writing a handler
(unfortunately). Therefore I post a small overview for interested
parties.

DISCLAIMER: The UI code will be refactored during the early phases of
the 2.16 phase (=very soon), so things might change a bit...

= Deskbar UIs=
The core of Deskbar lies in DeskbarApplet.py. This file essentially has
zero UI code in it (not 100% true). Deskbar is able to load UIs that
adhere to the ui/DeskbarUI.py interface. So writing a new UI basically
amounts to implementing that interface. UI loading is not entirely
dynamic at the moment[1], and the ones currently used are hardwired in
DeskbarApplet.py. For testing purposes you can overwrite the if/elif
statements in __init__() where self.ui is set.

= The Cuemiac =
Otherwise know as "The C", is short for
Cool�erEnhancedMatrixImmersiveAlignedCairo-widget (clearly). The
Cuemaic is the general layout widget for Deskbar - which replaced the
old one based on gtk.EntryCompletion. The old ui was used in the <= 0.8
series. It had to be replaced because it did not behave correctly with
async handlers. This was not fixable.

You will find the source code for the C in ui/cuemiac/Cuemiac.py. It is
based on gtk.TreeView, and therefore utilizes a model-view separation.
There are three interesting classes in that file:

	- CuemiacModel
	- CuemiacTreeView
	- CuemiacUI

and then some other which is not of interest right now. The last one
CuemiacUI implements the affore mentioned DeskbarUI interface. The two
top ones, Cuemiac{Model,TreeView} are the widgets displaying the actual
hits, and sorting them into categories.

If you are familiar with the Model View Controller architecture,
CuemiacUI is the controller of the above.

A new view would probably utilize the CuemiacModel and CuemiacTreeView
to display data, and then put those in a MyCustomUI. You can see this in
ui/entriac/CuemiacEntryUI.py (which is the one where the text entry is
embedded in the panel).

= Aligned Windows =
To align the popup windows (both search results and history) a class
ui/cuemiac/CuemiacAlignedWindow.py has been written. It is able to align
itself to a given widget.

= Focus =
It is tricky passing events back and forth between windows. In our case
the applet itself and the popup window with the search results. To focus
a window by an event from another window (when the user clicks up/down
from the entry the focus should go to the popup window fx.) you will
often have to do window.present_with_time(event.time).

Well I'm wasted :-) This might evolve into a wiki page sometime...
Anyway, cheers,

Mikkel

PS: Comments and questions are of course more than welcome!

[1]: Perhaps this is a worthwhile goal?