Ubuntu – way for non-experts to create new lenses/drawers for the Unity launcher

Note: The user visible name is Lenses, however in the code and packages they're still referred to as Places. "Places" as a term will be fully retired in 11.10

Both default Lenses, unity-place-files and unity-place-applications, are in fact based on public API exposed via libunity.

Unfortunately there are no API docs available for libunity yet - but that will change in the weeks to come. Monitor planet.ubuntu.com or watch the Natty archives for a libunity-doc package. For now there is a simple example in lp:unity-place-sample, if you cross ref that with https://wiki.ubuntu.com/Unity/Lenses you may have a chance of getting something going.

Another important library when writing lenses for Unity is Dee. It's a data model library used to do ad-hoc sharing of data models between processes (in this case the place daemon and Unity). Dee is fully documented and you can find the docs in the libdee-doc package (or you can build it yourself from lp:dee).

To grab the code for either project you can do:

bzr branch lp:unity-place-sample
bzr branch lp:dee

In general, I'd recommend using the toolkit supported ways to put menus in the global menubar... but, I'm assuming it's too late to convince you at this point :-) Also, I'll note that even thought we're using Dbusmenu and registration in 12.04 the goal is to move to GMenuModel and marking the window with its menus by 14.04, so this information will become dated. Ofcourse, the toolkit plug-ins will be updated ;-) (last time I'll try, I promise)

The basic principle involved is that we need to know what menus are associated with which window. We track the window using its XID and the menus are a path to the Dbusmenu Server on DBus. You'll need both of those pieces of information to register. The registration interface is pretty simple in that you basically pass both of those pieces of information to the registrar. The registrar's well known name on DBus is com.canonical.AppMenu.Registrar.

For an example of how this can work you can look at the mock-json-app sample code that is in indicator-appmenu. This is a small tool that will take the JSON file output by dbusmenu-dumper (which is in libdbusmenu-tools) and make a window that claims to have that menu. It also handles things like the appmenu crashing, which might not be really required for most application (though is really important in development :-) ).

To create a Dbusmenu Server you basically just need to allocate the object and tell it where to appear on DBus (so you can give the location to the registrar). For plugins like appmenu-gtk we use a generated path so that there is no conflict, but if you're controlling the app you can probably use a fixed path. Then you create a tree structure of Dbusmenu Menuitem objects. The root one isn't shown, but is passed to the Dbusmenu Server to start out the menus. The first level bellow the root will be shown as items across the Ubuntu Menubar.

Good luck, thanks to all the people who harassed me to answer this question. I still believe that you should use the toolkit support (I lied about it being the last time), but good luck!