unity-design team mailing list archive

[Ted Gould <ted@xxxxxxxxxxxxx>]

On Wed, 2010-03-10 at 09:39 +0100, Marcelo Hashimoto wrote:
> For a few weeks now, me and a friend have been planning
> to start a project that would make use of indicators.
> However, we are a little bit confused about how *exactly*
> they work and I decided to post some general questions
> in this list, that seemed to be the best place to ask.

Cool.  Can you give us a sneak peak? :)

> 1) The job of an INDICATOR-APPLET is to contain and display
> INDICATORS on the desktop. INDICATORS are, for the lack of
> a better word, "widgets" that cannot exist on the desktop
> on their own and need a container in order to do so. Those
> containers are currently INDICATOR-APPLETS, but they could
> easily be something else (i.e. there's nothing tying the
> concept specifically to panel applets)

Correct.

> 2) An INDICATOR-APPLET can contain as much INDICATORS as
> it wants. Currently, which INDICATORS each INDICATOR-APPLET
> contains and their order have to be hardcoded in the
> INDICATOR-APPLET source.

Correct.

> 3) LIBINDICATOR is the library needed to build INDICATORS
> and INDICATOR-APPLETS. An application should not need to
> use those directly.

Correct.

> 4) LIBINDICATOR, INDICATORS and INDICATOR-APPLETS are Gtk
> specific and the Qt equivalents are a work in progress. One
> example is the PLASMA-WIDGET-MESSAGING-INDICATOR, which is
> at the same time a Qt equivalent of INDICATOR-MESSAGES and
> an INDICATOR-APPLET containing it.

Mostly correct, more below.

> 5) LIBDBUSMENU is a toolkit-independent library that the
> applications can use to send menu objects via dbus. It is
> a concept that exists on its own and does not depend on
> anything specifically related to indicators. There are
> Gtk and Qt bindings for this library.

Correct.  There is a libdbusmenu-gtk which built along with libdbusmenu
but it is more or less the GTK bindings to libdbusmenu.

> 6) LIBINDICATE is a toolkit-independent wrapper library
> around LIBDBUSMENU for the communication between
> applications and INDICATORS (or the Qt equivalent to
> INDICATORS) via menu objects. There are Gtk and Qt
> bindings for this library.

No.  Libindicate is a library for applications to share messages over
dbus.  The idea is very similar to the application raising a flag and
saying "I have an interesting message."  It also allows for applications
to specify a few extra commands that aren't related to those flags as a
dbusmenu if they'd like.  There are QT and GTK bindings as well.  In
general, dbusmenu is point-to-point communication of menu structure
while libindicate is more of a bus topology.

> 7) LIBAPPINDICATOR is a Gtk-specific wrapper library around
> LIBDBUSMENU for the communication between applications and
> INDICATOR-APPLICATION. There is not a Qt equivalent yet.

No.  More below, hopefully it makes sense that there isn't a Qt
equivalent.

> 1) Why are INDICATORS and LIBINDICATOR toolkit-specific?
> Conceptually, aren't the only toolkit-specific parts
> supposed to be INDICATOR-APPLETS?

So, there has to be a line where we get toolkit specific and that line
is where the indicators get loaded and build menus.  All of the
indicators are divided into two components, a visualization component
and a policy component called the service.  So the only thing that is
toolkit specific is the visualization aspect, and that is mostly managed
by the parts of libindicator that you're probably thinking is the entire
indicator.

> 2) Why does the Gtk (Qt) bindings of LIBINDICATE do not
> use the Gtk (Qt) bindings of LIBDBUSMENU?

I think this might related to your confusion above, but I'll try to
answer anyway.  Basically because it doesn't doesn't need the GTK
bindings.  The only information that it needs is enough to relay the
details of the menu to the person who's rendering the menu.  It doesn't
need to render the menu itself.

> 3) Why is LIBAPPINDICATOR a wrapper directly around
> LIBDBUSMENU instead of being a wrapper around LIBINDICATE?
> It seems that LIBINDICATE specializes LIBDBUSMENU to
> INDICATORS and LIBAPPINDICATOR specializes LIBDBUSMENU
> to a *specific* INDICATOR, so it seems less redundant
> to wrap LIBAPPINDICATOR around LIBINDICATE.

There is some conflict in purposes of libindicate and libappindicator.
But, in general, libappindicator isn't a wrapper around dbusmenu it is a
library for signaling with a registration service to communicate the
location of a dbusmenu.  So it registers the menu and other information
with that service and the way it does that is using the KDE Status
Notifier protocol.

Libindicate and libappindicator have different requirements when it
comes to availability.  libindicate does not require a single service to
register and can have multiple people on the bus.  Any of them having an
error should not effect the others.  They also in general, transfer
different information.  libappindicator is designed for putting a single
app in a menu with an icon, while libindicate is more focused around
"counting" which is important for messaging applications.

> 4) Why does the specification of which INDICATORS go
> inside each INDICATOR-APPLET, and their order, are
> hardcoded in the INDICATOR-APPLET code? Currently, the
> only "configuration" available to the end user is
> uninstalling the indicators they don't want and the
> only way for developers to experiment with, for example,
> the order of INDICATORS is constant recompilation.

Didn't see a reason to make it more complex.

> Finally, the most important questions: am I being
> redundant and all those conceptual questions are
> easily answered by a wiki/doc/whatever somewhere?
> If the answer is "no", I volunteer myself to start
> one.

I don't think there's a good source, you should start one :)

> Also, where I can find complete API documentation
> of everything above? The only thing with a -doc
> package I've seen is LIBAPPINDICATOR.

All the APIs are documented, we just haven't gotten all the
infrastructure setup to build the -doc packages.  Again, this would be a
wonderful way to contribute.  I'd love to get set up where the
documentation is set to build into webpages.  It's all gtk-doc which has
some really nice features there, but I haven't mastered them :-/

> Again, sorry for the long mail and hope someone
> can answer everything.

No problem.  Hope I got close. :)

		--Ted

Attachment: signature.asc
Description: This is a digitally signed message part