Merge lp:~unity-team/libunity/launcher-api into lp:libunity

[Mikkel Kamstrup Erlandsen]

This is the initial cut on the launcher API. It introduces three new public classes:

 Unity.LauncherEntry : a thin wrapper for some DBus logic that syncs the properties in a clever way to Unity. You can control count, progress, emblem, and quicklist.

 Unity.Inspector : a singleton "hub" for collecting metadata about the running, or not running, Unity process. In particular whether Unity is running or not.

 Unity.Serializable : An interface for objects that can be transformed into variants.

I need to add some more tests that assert that all the clever DBus caching and re-syncing works as it should (only manually verified at this point), but this will come in a different branch because it requires some fiddling to get right.

[Neil J. Patel (njpatel)]

Looks sexy.

review: Approve

=== modified file 'configure.ac'
--- configure.ac	2011-01-21 09:14:30 +0000
+++ configure.ac	2011-01-27 16:02:15 +0000
@@ -88,10 +88,11 @@
 PKG_CHECK_MODULES(GIO_UNIX2, [gio-unix-2.0])
 PKG_CHECK_MODULES(GEE, [gee-1.0 >= 0.6.0])
 PKG_CHECK_MODULES(DEE, [dee-1.0 >= 0.5.2])
+PKG_CHECK_MODULES(DBUSMENU, [dbusmenu-glib-0.4 >= 0.3.93])
 
-LIBUNITY_CFLAGS="$GLIB2_CFLAGS $GOBJECT2_CFLAGS $GIO2_CFLAGS $GIO_UNIX2_CFLAGS $GEE_CFLAGS $DEE_CFLAGS"
-LIBUNITY_LIBS="$GLIB2_LIBS $GOBJECT2_LIBS $GIO2_LIBS $GIO_UNIX2_LIBS $GEE_LIBS $DEE_LIBS"
-LIBUNITY_PACKAGES="--pkg glib-2.0 --pkg gobject-2.0 --pkg gio-2.0 --pkg gio-unix-2.0 --pkg gee-1.0 --pkg dee-1.0"
+LIBUNITY_CFLAGS="$GLIB2_CFLAGS $GOBJECT2_CFLAGS $GIO2_CFLAGS $GIO_UNIX2_CFLAGS $GEE_CFLAGS $DEE_CFLAGS $DBUSMENU_CFLAGS"
+LIBUNITY_LIBS="$GLIB2_LIBS $GOBJECT2_LIBS $GIO2_LIBS $GIO_UNIX2_LIBS $GEE_LIBS $DEE_LIBS $DBUSMENU_LIBS"
+LIBUNITY_PACKAGES="--pkg glib-2.0 --pkg gobject-2.0 --pkg gio-2.0 --pkg gio-unix-2.0 --pkg gee-1.0 --pkg dee-1.0 --pkg Dbusmenu-Glib-0.4"
 AC_SUBST(LIBUNITY_CFLAGS)
 AC_SUBST(LIBUNITY_LIBS)
 AC_SUBST(LIBUNITY_PACKAGES)

=== modified file 'src/Makefile.am'
--- src/Makefile.am	2011-01-20 10:29:21 +0000
+++ src/Makefile.am	2011-01-27 16:02:15 +0000
@@ -48,10 +48,13 @@
 
 libunity_la_VALASOURCES = \
   unity-appinfo-manager.vala \
+  unity-inspector.vala \
   unity-io.vala \
+  unity-launcher.vala \
   unity-place.vala \
   unity-place-activation.vala \
-  unity-place-browser.vala
+  unity-place-browser.vala \  
+  unity-serializable.vala
 
 
 libunity_la_APIFILES = \

=== added file 'src/unity-inspector.vala'
--- src/unity-inspector.vala	1970-01-01 00:00:00 +0000
+++ src/unity-inspector.vala	2011-01-27 16:02:15 +0000
@@ -0,0 +1,121 @@
+/*
+ * Copyright (C) 2011 Canonical, Ltd.
+ *
+ * This library is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License
+ * version 3.0 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License version 3.0 for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>.
+ *
+ * Authored by Mikkel Kamstrup Erlandsen <[e-mail]>
+ *
+ */
+
+/*
+ * IMPLEMENTATION NOTE:
+ * We want the generated C API to be nice and not too Vala-ish. We must
+ * anticipate that libunity consumers will be written in both Vala , C,
+ * and through GObject Introspection
+ *
+ */
+ 
+using GLib;
+ 
+namespace Unity {
+
+  /**
+   * The Unity.Inspector is a singleton that can be used to inspect the
+   * state of Unity.
+   *
+   * One of the most basic and most useful applications of the inspector
+   * is to check if Unity is running or not.
+   *
+   */
+  public class Inspector : Object
+  {
+    /**
+     * Boolean property determining whether Unity is running or not. You
+     * can use this property to determine whether Unity is running or not.
+     */
+    public bool unity_running { get { return _unity_running; } }
+    private bool _unity_running = false;
+    
+    /**
+     * Property holding the unique DBus name of the Unity process if
+     * Unity is running, or null otherwise.
+     */
+    public string? unity_bus_name { get { return _unity_bus_name; }  }
+    private string? _unity_bus_name = null;
+    
+    private DBusConnection    bus;
+    private uint              unity_watcher;
+    private static Inspector? singleton = null;
+    
+    /**
+     * Get the default singleton Unity.Inspector instance, creating it
+     * dynamically if necessary.
+     *
+     * @return The singleton Unity.Inspector. If calling from C do not
+     *         free this instance.
+     *
+     */
+    public static unowned Inspector get_default ()
+    {
+      if (singleton == null)
+        singleton = new Inspector ();
+        
+      return singleton;
+    }
+    
+    /* Constructor is private to bar 3rd parties from creating instances */
+    private Inspector ()
+    {
+      try {
+        bus = Bus.get_sync (BusType.SESSION);
+        unity_watcher = Bus.watch_name_on_connection (bus, "com.canonical.Unity",
+                                                      BusNameWatcherFlags.NONE,
+                                                      on_unity_appeared,
+                                                      on_unity_vanished);
+      } catch (IOError e) {
+        critical ("Unable to connect to session bus: %s", e.message);
+      }
+      
+    }
+    
+    private void on_unity_appeared (DBusConnection conn,
+                                    string         name,
+                                    string         name_owner)
+    {
+      if (name != "com.canonical.Unity")
+        {
+          critical ("Internal error in libunity: Got name owner notification " +
+                    "from '%'. Expected 'com.canonical.Unity'", name);
+          return;
+        }
+    
+      _unity_running = true;
+      _unity_bus_name = name_owner;
+      notify_property ("unity-running");
+      notify_property ("unity-bus-name");
+    }
+    
+    private void on_unity_vanished (DBusConnection conn,
+                                    string         name)
+    {
+      _unity_running = false;
+      _unity_bus_name = null;
+      notify_property ("unity-running");
+      notify_property ("unity-bus-name");
+    }
+    
+  } /* class Unity.Inspector */
+  
+
+} /* namespace */

=== added file 'src/unity-launcher.vala.OTHER'
--- src/unity-launcher.vala.OTHER	1970-01-01 00:00:00 +0000
+++ src/unity-launcher.vala.OTHER	2011-01-27 16:02:15 +0000
@@ -0,0 +1,267 @@
+/*
+ * Copyright (C) 2011 Canonical, Ltd.
+ *
+ * This library is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License
+ * version 3.0 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License version 3.0 for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>.
+ *
+ * Authored by Mikkel Kamstrup Erlandsen <[e-mail]>
+ *
+ */
+
+/*
+ * IMPLEMENTATION NOTE:
+ * We want the generated C API to be nice and not too Vala-ish. We must
+ * anticipate that libunity consumers will be written in both Vala , C,
+ * and through GObject Introspection
+ *
+ */
+ 
+using GLib;
+ 
+namespace Unity {
+
+  /* Private class to wire up the DBus stuff. Private so that we don't
+   * leak DBus implementation details into the public API */
+  [DBus (name = "org.canonical.Unity.LauncherEntry")]
+  private class LauncherEntryDBusImpl : Object
+  {
+    
+    public weak LauncherEntry? owner;
+    
+    public LauncherEntryDBusImpl (DBusConnection conn,
+                                  ObjectPath     object_path,
+                                  LauncherEntry  owner)
+    {
+      try {
+        conn.register_object (object_path, this);
+      } catch (IOError e) {
+        warning ("Unable to connecto to session bus. Unable to control " +
+                 "LauncherEntry for %s", object_path);
+      }
+      
+      this.owner = owner;
+    }
+
+    public signal void update (string app_uri,
+                               HashTable<string,Variant> properties);
+    
+    public HashTable<string,Variant> query ()
+    {
+      /*var props = new HashTable<string,Variant>(str_hash, str_equal);
+      
+      if (owner == null)
+        return props;
+      
+      props.insert ("count", owner.count);
+      props.insert ("count-visible", owner.count_visible);
+      props.insert ("progress", owner.progress);
+      props.insert ("progress-visible", owner.progress_visible);
+      props.insert ("emblem", owner.emblem == null ? "" : owner.emblem);
+      props.insert ("emblem-visible", owner.emblem_visible);
+      
+      if (owner.quicklist != null)
+        props.insert ("quicklist", owner._object_path);
+      
+      return props;*/
+      if (owner == null)
+        return new HashTable<string,Variant>(str_hash, str_equal);
+      
+      return collect_launcher_entry_properties (owner);
+    }
+  }
+
+  /**
+   * This class represents your control point for your application's icon
+   * in the Unity Launcher. You can control properties such as a counter,
+   * progress, or emblem that will be overlaid on your application's launcher
+   * icon. You can also set a quicklist on it by setting the "quicklist"
+   * property to point at the Dbusmenu.Menuitem which is the root of your
+   * quicklist.
+   *
+   * Create a LauncherEntry by giving your desktop file id to the constructor
+   * (eg. "myapp.desktop").
+   */
+  public class LauncherEntry : Serializable, Object
+  {
+    public string app_uri {get; set construct; }
+    
+    public int64 count { get; set; default = 0; }
+    public bool count_visible { get; set; default = false; }
+    
+    public double progress { get; set; default = 0.0; }
+    public bool progress_visible { get; set; default = false; }
+    
+    public string? emblem { get; set; default = null; }
+    public bool emblem_visible { get; set; default = false; }
+    
+    private Dbusmenu.Menuitem? _quicklist;
+    public Dbusmenu.Menuitem? quicklist {
+      get { return _quicklist; }
+      set {
+        _quicklist = value;
+        if (_quicklist != null) {
+          _quicklist_server = new Dbusmenu.Server (_object_path);
+          _quicklist_server.root_node = _quicklist;
+        }
+      }
+    }
+        
+    private HashTable<string,Variant> _queued_properties;
+    private Dbusmenu.Server?          _quicklist_server;
+    private uint                      _property_source_id;
+    private DBusConnection            _bus;
+    private LauncherEntryDBusImpl     _dbus_impl;
+    internal ObjectPath                _object_path;
+  
+    construct
+    {     
+      _queued_properties = new HashTable<string,Variant>(str_hash, str_equal);
+      _quicklist_server = null;
+      _property_source_id = 0;
+     
+     try {       
+        _bus = Bus.get_sync (BusType.SESSION);
+        _object_path = new ObjectPath (@"/com/canonical/unity/launcherentry/$(app_uri.hash())");
+        _dbus_impl = new LauncherEntryDBusImpl (_bus, _object_path, this);
+      
+        var inspector = Inspector.get_default();
+        inspector.notify["unity-running"].connect (on_unity_running_changed);
+      
+        this.notify.connect (queue_property_notification);
+      } catch (IOError e) {
+        critical ("Unable to connect to session bus: %s", e.message);
+      }
+      
+    }
+  
+    /**
+     * Create a new LauncherEntry for the desktop file id of your application.
+     *
+     * The desktop file id is defined as the basename of your application's
+     * .desktop file (including the extension), eg. myapp.desktop.
+     */
+    public LauncherEntry(string desktop_id)
+    {
+      Object (app_uri : "application://" + desktop_id);
+    }
+    
+    /* Implement interface Unity.Serializable */
+    public Variant serialize ()
+    {
+      /* Vala will automagically marhshal the properties into a 'a{sv}' Variant */
+      return collect_launcher_entry_properties (this);
+    }
+    
+    private void queue_property_notification (Object self, ParamSpec pspec)
+    {
+      Variant? v;
+      ObjectPath object_path;
+      
+      switch (pspec.name)
+      {
+        case "count":
+          v = this.count;
+          break;
+        case "count-visible":
+          v = this.count_visible;
+          break;
+        case "progress":
+          v = this.progress;
+          break;
+        case "progress-visible":
+          v = this.progress_visible;
+          break;
+        case "emblem":
+          v = this.emblem != null ? this.emblem : "";
+          break;
+        case "emblem-visible":
+          v = this.emblem_visible;
+          break;
+        case "quicklist":
+          if (_quicklist_server != null)
+            {
+              _quicklist_server.get ("dbus-object", out object_path);
+              v = object_path;
+            }
+          else
+            {
+              v = null; // FIXME: How to retract quicklist
+            }
+          break;
+        default:
+          /* Assume that this is a property we want to ignore wrt DBus */
+          v = null;
+          break;
+      }
+      
+      if (v != null)
+        {
+          _queued_properties.insert (pspec.name, v);
+        }
+      
+      if (_property_source_id == 0)
+        {
+          _property_source_id = Idle.add (dispatch_property_notification);
+        }
+    }
+    
+    private bool dispatch_property_notification ()
+    {
+      /* Emit DBus signal with our changes if Unity is running.
+       * If it's not running at this point we'll sync all our state
+       * when it gets up */
+      if (Inspector.get_default().unity_running)
+        _dbus_impl.update (app_uri, _queued_properties);
+
+      /* Reset state */
+      _property_source_id = 0;
+      _queued_properties.remove_all ();
+      
+      return false;
+    }
+    
+    /* Callback for when Unity comes or goes */
+    private void on_unity_running_changed (Object _inspector, ParamSpec pspec)
+    {
+      Inspector inspector = _inspector as Inspector;
+      
+      /* If Unity has just come online sync all out props to it */
+      if (inspector.unity_running)
+        {
+          Variant props = serialize ();
+          _bus.emit_signal (null, _object_path,
+                            "com.canonical.Unity.LauncherEntry",
+                            "Update", new Variant.tuple(new Variant[1]{props}));
+        }
+    }
+    
+  } /* class Unity.LauncherEntry */
+
+  private static HashTable<string,Variant> collect_launcher_entry_properties (LauncherEntry l)
+  {
+    var props = new HashTable<string,Variant>(str_hash, str_equal);
+    
+    props.insert ("count", l.count);
+    props.insert ("count-visible", l.count_visible);
+    props.insert ("progress", l.progress);
+    props.insert ("progress-visible", l.progress_visible);
+    props.insert ("emblem", l.emblem == null ? "" : l.emblem);
+    props.insert ("emblem-visible", l.emblem_visible);
+    
+    if (l.quicklist != null)
+      props.insert ("quicklist", l._object_path);
+    
+    return props;
+  }  
+
+} /* namespace */

=== added file 'src/unity-serializable.vala'
--- src/unity-serializable.vala	1970-01-01 00:00:00 +0000
+++ src/unity-serializable.vala	2011-01-27 16:02:15 +0000
@@ -0,0 +1,51 @@
+/*
+ * Copyright (C) 2011 Canonical, Ltd.
+ *
+ * This library is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License
+ * version 3.0 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License version 3.0 for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>.
+ *
+ * Authored by Mikkel Kamstrup Erlandsen <[e-mail]>
+ *
+ */
+
+/*
+ * IMPLEMENTATION NOTE:
+ * We want the generated C API to be nice and not too Vala-ish. We must
+ * anticipate that libunity consumers will be written in both Vala , C,
+ * and through GObject Introspection
+ *
+ */
+ 
+using GLib;
+ 
+namespace Unity {
+
+  /**
+   * Interface for anything that can be serialized to a GVariant.
+   * This is useful both for persisting stuff to disk and for
+   * sending across DBus.
+   */
+  public interface Serializable
+  {
+    /**
+     * Create a GVariant describing the instance being serialized.
+     *
+     * @return A non-floating reference to a GVariant. If calling from C
+     *         free it with g_variant_unref().
+     */
+    public abstract Variant serialize ();
+    
+  } /* interface Unity.Serializable */
+  
+
+} /* namespace */

=== modified file 'test/vala/Makefile.am'
--- test/vala/Makefile.am	2011-01-11 22:24:05 +0000
+++ test/vala/Makefile.am	2011-01-27 16:02:15 +0000
@@ -27,8 +27,9 @@
 test_vala_SOURCES = \
   test-appinfo-manager.vala \
   test-io.vala \
-  test-place.vala \
+  test-launcher.vala \
   test-place-browser.vala \
+  test-place.vala \  
   test-vala.vala
 
 EXTRA_DIST += config.vapi

=== added file 'test/vala/test-launcher.vala'
--- test/vala/test-launcher.vala	1970-01-01 00:00:00 +0000
+++ test/vala/test-launcher.vala	2011-01-27 16:02:15 +0000
@@ -0,0 +1,50 @@
+/* -*- Mode: vala; indent-tabs-mode: nil; c-basic-offset: 2; tab-width: 2 -*- */
+/*
+ * Copyright (C) 2010 Canonical Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 3 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Authored by Mikkel Kamstrup Erlandsen <[e-mail]>
+ *
+ */
+using Unity;
+
+namespace Unity.Test
+{
+  public class LauncherSuite
+  {
+    public LauncherSuite ()
+    {
+      GLib.Test.add_data_func ("/Unit/Launcher/Empty",
+                               LauncherSuite.test_empty_launcher_entry);
+    }
+
+    internal static void test_empty_launcher_entry()
+    {
+      var l = new Unity.LauncherEntry("foo.desktop");
+      assert (l is LauncherEntry);
+      assert (l.app_uri == "application://foo.desktop");
+      
+      assert (l.count == 0);
+      assert (l.count_visible == false);
+      
+      assert (l.progress == 0.0);
+      assert (l.progress_visible == false);
+      
+      assert (l.emblem == null);
+      assert (l.emblem_visible == false);
+      
+      assert (l.quicklist == null);
+    }
+  }
+}

=== modified file 'test/vala/test-vala.vala'
--- test/vala/test-vala.vala	2011-01-20 10:00:26 +0000
+++ test/vala/test-vala.vala	2011-01-27 16:02:15 +0000
@@ -27,6 +27,7 @@
     PlaceBrowserSuite place_browser;
     IOSuite io;
     AppInfoManagerSuite appinfo_manager;
+    LauncherSuite launcher;
 
     Environment.set_variable ("XDG_DATA_HOME", Config.TESTDIR+"/data", true);
     Test.init (ref args);
@@ -39,6 +40,8 @@
     io = new IOSuite ();
     appinfo_manager = new AppInfoManagerSuite ();
 
+    launcher = new LauncherSuite ();
+
     Test.run ();
 
     return 0;

=== modified file 'unity.pc.in'
--- unity.pc.in	2011-01-11 17:37:13 +0000
+++ unity.pc.in	2011-01-27 16:02:15 +0000
@@ -8,5 +8,5 @@
 Version: @VERSION@
 Libs: -L${libdir} -lunity
 Cflags: -I${includedir}/unity/unity
-Requires: glib-2.0 gthread-2.0 gobject-2.0 gio-2.0 gio-unix-2.0 dee-1.0 gee-1.0
+Requires: glib-2.0 gthread-2.0 gobject-2.0 gio-2.0 gio-unix-2.0 dee-1.0 gee-1.0 dbusmenu-glib-0.4