Ubuntu Wiki

Launcher API

We support adding quicklists, numbers, and progress bars for apps in the Unity Launcher:

Using the Launcher API

Each launcher icon can be controlled remotely by a discrete LauncherEntry object. New launcher entry object may be created by call unity_launcher_entry_new (char *id); where id is the name of the desktop file shipped by the application you wish to control. For example evolution ships "evolution.desktop" or empathy ships "empathy.desktop"

LauncherEntries are able to control 3 major components of a Launcher Icon:

Count

The first aspect they can control is the count associated with the icon. The count may be set by calling

unity_launcher_entry_set_count (UnityLauncherEntry *self, int count);

This will remotely prime the count, then calling

unity_launcher_entry_set_count_visible (UnityLauncherEntry *self, gboolean visible)

can toggle its visible status. Updates to the count and other properties are live, unsetting and resetting the visibility is not require nor is it encouraged.

Progress

progress can be set by

unity_launcher_entry_set_progress (UnityLauncherEntry *self, gdouble progress)

and made visible by calling

unity_launcher_entry_set_progress_visible (UnityLauncherEntry *self, gbloolean visible);

Quicklists

Quicklists may also be created and appended to the launcher. To create a quicklist a root node must first be created as a container, and then child nodes are added to it. This final result may be packed into the launcher which is then shipped over the bus to Unity. Updates to the quicklist are also live. Rather than describe the entire API, an example of using quicklist (as well as progress and count) is provided below using the vala bindings.

It is important to note that the main loop must be invoked for the program to actual work. Libunity requires the usage of the main loop as work may be done async.

Vala Example

/* Compile with: valac --pkg unity --pkg dee-1.0 --pkg gee-1.0 --pkg Dbusmenu-Glib-0.4 launcherexample.vala */
namespace LauncherExample {

  public static void main ()
  {
    /* Pretend to be evolution for the sake of the example */
    var l = new Unity.LauncherEntry ("evolution.desktop");

    /* Show a count of 124 on the icon */
    l.count = 124;
    l.count_visible = true;
    
    /* set the progress of the icon */
    l.progress = 0.8;
    l.progress_visible = true;
    
    /* We also want a quicklist */
    var ql = new Dbusmenu.Menuitem ();
    var item1 = new Dbusmenu.Menuitem ();
    item1.property_set (Dbusmenu.MENUITEM_PROP_LABEL, "Item 1");
    var item2 = new Dbusmenu.Menuitem ();
    item2.property_set (Dbusmenu.MENUITEM_PROP_LABEL, "Item 2");
    ql.child_append (item1);
    ql.child_append (item2);
    l.quicklist = ql;

    new MainLoop().run();
  }
  
}