After all the terrific feedback and contributions we received from community contributors as a result of my Quicklists article, I’ve been asked to talk about how to contribute to improving another feature of Unity, the Applications Lens.

Search is the heart of the Unity Dash, and making search better is great way to contribute to the overall quality and usability of Ubuntu.  And just like Quicklists, there are ways you can do this without being a developer.  In this article, I will show you how to add Keywords to an application that will be used by the Dash’s search function.

Just like in my previous tutorial on Quicklists, I will once again be using Geany as my example application since it is one of my most-used programs.  Geany will be found in a search for “IDE” or “Development”, thanks to those words being in the Comment and GenericName fields of it’s .desktop file.  However, I think it should also be found in a search for “Code” and “Programming”, which it currently does not.

Step 0: File bug reports

This wasn’t part of the Quicklist tutorial, because I had already  filed bugs for the apps we were targetting.  But this time there is no list, so it’s up to you to make sure there is a bug report.  For ubuntu, you can file it against:

https://bugs.launchpad.net/ubuntu/+source/<source_name>/

It’s equally important to file a bug in the upstream’s Bug Tracker.  Refer to the stems up my post about upstreaming your quicklists for how to find your upstream.

Once you  have your bugs filed, post a link to them in the comments so that others know you are working on them.

bzr branch ubuntu:geany

If you followed the Quicklist tutorial, you’ll have already done this.  However, if your merge proposal hasn’t been accepted yet, it’ll be easier to do these changes on a clean branch.  You can give the name of a new directory for this checkout by running:

bzr branch ubuntu:geany ./geany-keywords

Step 2: Adding keywords

Again, just like with Quicklists, you first need to locate the .desktop file for your application.  For me, it was located in the root of the branch in a file called “geany.desktop.in”.  If you don’t see it in the root of your project’s branch, try running this command:

find ./ -name "*.desktop*"

This may not look exactly like the file in your /usr/share/applications/, since some processing is done to add translated strings for the application name and comments.  But as long as you are just adding the Keywords item to the bottom of the file you shouldn’t have to worry about that.

Next you  should look for deprecated keyword fields.  ”Keywords” is a new part of the XDG specification, but your application may have already been using the desktop-specific field “X-GNOME-Keywords”.  If it does, go ahead and rename it to “Keywords”.  Also check for the existence of fields starting with an underscore, like “_Name”.  If your .desktop file has those, that means it’s probably setup for translations already, and you should use “_Keywords” instead, so that they can be translated as well.

For geany, there was no existing Keywords field of any kind, but it was setup for translations, so I used the following:

mhall@mhall-laptop:~/projects/Ubuntu/unity/quicklists/geany$ bzr diff
=== modified file 'geany.desktop.in'
--- geany.desktop.in	2012-02-24 19:30:41 +0000
+++ geany.desktop.in	2012-02-27 18:31:39 +0000
@@ -10,3 +10,4 @@
 Categories=GTK;Development;IDE;
 MimeType=text/plain;text/x-chdr;text/x-csrc;text/x-c++hdr;text/x-c++src;text/x-java;text/x-dsrc;text/x-pascal;text/x-perl;text/x-python;application/x-php;application/x-httpd-php3;application/x-httpd-php4;application/x-httpd-php5;application/xml;text/html;text/css;text/x-sql;text/x-diff;
 StartupNotify=true
+_Keywords=Code;Editor;Programming;

Step 3: Submitting to Ubuntu

Now you need to send your changes to Ubuntu.  This is very similar to what we did for Quicklists, but I’ve added one extra piece to the commit command.

bzr commit -m "Add Keywords to .desktop file" --fixes lp:942154
bzr push lp:~mhall119/ubuntu/precise/geany/add_keywords

By passing the –fixes flag, along with your Launchpad bug #, to the bzr commit command, you will automatically link your new branch with the bug report you created in step 0.

The next step is to once again propose that your changes be merged into the Ubuntu package. To do that, run the following command to open the Launchpad page for your new branch:

bzr lp-open

On that page you’ll see a link labeled “Propose for merging”, click that and fill out the form on the next page to create your merge proposal.

Step 4: Submitting to Upstream

The final step is to send your changes upstream as well.  This is good practice whenever you are making changes, plus it makes it easier for Ubuntu’s package maintainers.  Since every upstream is different in how they want to get submissions, I recommend following my previous upstreaming tutorial for this step.

There has been a fantastic amount of feedback and contributions being made by folks who have been following my recent posts, and we’ve already had some of those contributions landing in Ubuntu 12.04.  But we’re not done yet!

Ubuntu means “I am who I am, because of who we all are”.  In a very literal sense, Ubuntu is what it is, because of what other distros are.  We all bring together the best open source software from upstream developers, and we should all be giving our improvements back to those developers.  Unity may be the default desktop on Ubuntu, but it’s also been ported to ArchLinux and SuSe, and is making it way to Fedora too.  That means that your Quicklist contribution can help more than just Ubuntu, all you need to do is submit it upstream.

Step 1: Find your Upstream

While all of Ubuntu’s package sources use Launchpad, and are therefore all in the same place, your upstream developers will all of their own separate spaces.  Some are rather easy to find, for example Firefox is developed over on mozilla.org.  Others may use GitHub, SourceForge, or their own sites.  So you first task if to find out where the code is developed.

Step 2: Talk to your Upstream

Once you’ve found their development home, look for ways of contacting the developers.  Usually there will me an email/mailing list available, an IRC channel or a forum.  Whatever method they prefer, us it to ask the developers how they want you to submit your patch.  Most developers love being contacted by somebody who already has a patch written.

Step 3: Submit your changes

Depending on your upstream’s development process, they may want a patch file with your changes, or they might ask you to use their version control system of choice (svn, git, etc) to submit your change in a way that is easy for them to merge.  Some, especially Debian, may request a patch for the package itself.  This is why Step 2 is so important, you need to know how to submit it in order for it to be accepted.  Don’t worry if you don’t know how do what they want, ask them to help you learn it.  Again, developers like people who come to them with patches.

For Geany, I first found their website, geany.org, and from there a link to their Feature Tracker on SourceForge.  I also found their IRC channel, #geany on freenode, and was in contact with their developers there.  In the end, I was asked to create a fork of their code on GitHub, and submit my change as a Pull Request.

Step 4: Updated your Merge Proposal

Once you’ve submitted you changes upstream, leave a comment to that effect in your merge proposal.  Ubuntu developers don’t like to keep custom changes in Ubuntu, and your merge proposal is much more likely to be accepted if they know the change will eventually be made in the upstream project as well.

Step 5: Stay involved with your Upstream

If you were working on a program you like, don’t let this be the end of your contribution!  You now have experience making and submitting changes (to both Ubuntu and Upstream), and you are forming a relationship with the upstream developers.  Keep up with both of those, as they will be invaluable assets to you.

Since almost all of recommended packages in my original post have been tackled already thanks to Nekhelesh Ramananthan and David Baucum, here’s a new list for those of you who are still itching to knock a few out.

This list contains some of the most popular downloads from the Ubuntu Software Center that don’t have a Quicklist in Precise.  Not all of them will have useful command line options to make shortcuts for, so if you run across one of those just mention it in the comments and I’ll take it off the list.

Available

• audacity
• filezilla
• compizconfig-settings-manager
• cheese
• adobe-flashplugin
• libreoffice-writer
• emesene
• smplayer
• audacious
• wesnoth-1.8
• blender
• stellarium
• supertuxkart
• calibre
• virtualbox-ose

Done

• k3b done!
• rhythmbox done!
• pidgin done!
• remmina done!

Not Available

• firefox doesn’t properly handle command line options
• vlc doesn’t support command line options
• skype does not support command line options
• gparted only supports 1 commandline option which is useless
• gtk-recordmydesktop does not support command line options
• openshot only supports 1 commandline option which is useless
• eclipse does not support command line options
• ubuntuone-control-panel needs dynamic quicklist (required coding)

Jorge Castro has also linked to an AskUbuntu page that lists many pre-made Quicklists for various apps that just need to be made in a bzr branch and turned into a merge proposal, which is another great and simple way to contribute to Ubuntu.

Last night I posted about how non-developers can directly contribute to the Unity desktop experience, and this morning I was greated by not one, but two contributions already made by Nekhelesh Ramananthan.

First he added player controls to Totem, then he added shortcuts for Update Manager and PPA management to the Software Center launcher. That is some awesome work.

Thanks Nekhelesh!

So you want to contribute to Ubuntu’s Unity desktop, but you’re not a software developer?  No problem, there are still plenty of things you can do.  And not just in terms of documentation and translations either, there are ways to contribute directly to the desktop without having to know any programming languages.  One of these is adding Quicklists to application launcher.

Quicklists can be added dynamically from within the program code, but they can also be defined statically outside of it, in a simple text file.  It’s these static Quicklists that anybody can contribute.

For this post, I’m going to walk through the process of adding a Quicklist to Geany, my personal programming editor of choice.  You can add one for your favorite app, of choose from one of the following popular applications that are in need of a Quicklist:

• Empathy done!
• Gimp done!
• Brasero done!
• LibreOffice
• SMPlayer
• K3B
• Totem done!
• More target applications…

Step 1: Getting the package code

Everything in Ubuntu exists in bzr, which makes getting the source for the package easy.  just “bzr branch ubuntu:<project>”.  For geany, this is what I ran:

bzr branch ubuntu:geany

 Step 2: Add your Quicklist items

The first think you need to do is locate the .desktop file for your application.  For me, it was located in the root of the branch in a file called “geany.desktop.in”.  If you don’t see it in the root of your project’s branch, try running this command:

find ./ -name "*.desktop*"

This may not look exactly like the file in your /usr/share/applications/, since some processing is done to add translated strings for the application name and comments.  But as long as you are just adding the Quicklist items to the bottom of the file you shouldn’t have to worry about that.

The next step is to add your Quicklist shortcuts following this specification:

mhall@mhall-laptop:~/projects/Ubuntu/unity/quicklists/geany$ bzr diff
=== modified file 'geany.desktop.in'
--- geany.desktop.in 2011-05-28 19:49:19 +0000
+++ geany.desktop.in 2012-02-22 01:18:55 +0000
@@ -10,3 +10,9 @@
Categories=GTK;Development;IDE;
MimeType=text/plain;text/x-chdr;text/x-csrc;text/x-c++hdr;text/x-c++src;text/x-java;text/x-dsrc;text/x-pascal;text/x-perl;text/x-python;application/x-php;application/x-httpd-php3;application/x-httpd-php4;application/x-httpd-php5;application/xml;text/html;text/css;text/x-sql;text/x-diff;
StartupNotify=true
+Actions=New
+
+[Desktop Action New]
+Name=Open a New Instance
+Exec=geany --new-instance
+

(UPDATE 2012-02-28: A new XDG spec has been approved to make Quicklists desktop agnostic.  The Unity documentation has the new examples, and I have update the snippet above to match.)

As you can see in the example above, there isn’t much you need to do to add a Quicklist shortcut.  Calling the application’s binary with a different argument (as I did here with –new-instance) is a common and easy shortcut.  You can usually find all the available arguments to your application by calling with with –help.

 Step 3: Submitting your changes

Now that you’ve made your changes, we need to get them back into the main package.  Chances are you don’t have permission to apply them directly (otherwise you wouldn’t need this tutorial), so instead you’re going to put it somewhere else.

bzr commit -m "Add a Unity Quicklist"
bzr push lp:~mhall119/ubuntu/precise/geany/add_quicklist

This will put your changes on Launchpad in a place that the people who actually can apply it to the main packages can see your work.  But just because they can see it doesn’t mean they will see it, at least not without a little prompting from you.

To open the page on Launchpad that you just created (with your bzr push), run the following:

bzr lp-open

On that page you’ll see a link labeled “Propose for merging”, click that and fill out the form on the next page to create your merge proposal.

Step 4: Recompiling your kernel

Just kidding, there is no step 4.  You’re done!  You’ve contributed to making Ubuntu and Unity a better experience for millions of users.  Congratulations, and thank you!

There have been some recent accusation that the Ubuntu community isn’t taking criticism well.  However, those making the accusations seem to have a misunderstanding about what exactly criticism is.  In an effort to improve the quality of that feedback, I’ve put together a short, simple list of things you can check to make sure your criticism is in fact criticism.

1) “It sucks” is not criticism

It’s an insult.  It means “I have no respect for you, your time, or your talents”.  Don’t be surprised when the recipient of this message is not inclined to help you, or even listen to you, afterwards.

2) “I don’t like it” is not criticism

It’s complaining.  In order to elevate complaining to criticism, you need to explain why it is bad in a way that gives enough information for it to be improved.  If you are not capable of explaining why it is bad, then you don’t fully understand why you don’t like it.  And if you don’t understand why you don’t like it, what hope do we have of knowing how to fix it?

3) “It’s not perfect” is not criticism

We know it’s not perfect.  It’s not perfect because we are not perfect.  Another consequence of our being mortal is the fact that we don’t necessarily know where it’s not perfect, so please go back and read #2 again.

4) “Make it more like X” is not criticism

If what you  really want is X, then use X.  If you  think X is doing something better, then explain what it is and why it is better in a way that is more than just “It is better because X has it, and X is better”.  Again go back and re-read #2.

5) “Turn it into something different” is not criticism

Just because something isn’t what you want, doesn’t mean it’s not what it is supposed to be.  Don’t ask for changes to the fundamental nature of something. If something is fundamentally different from what you want, look for something else.

If your feedback doesn’t fall into one of these five areas, then there’s a very good chance that it will be welcomed and worked on by the Ubuntu community.  If it does, then I would seriously recommend going back and re-thinking your position.

One of the most requesting things since I first introduced Singlet was to have a Quickly template for creating Unity Lenses with it.  After weeks of waiting, and after upgrading Singlet to work in Precise, and getting it into the Universe repository for 12.04, I finally set to work on learning enough Quickly internals to write a template.

It’s not finished yet, and I won’t guarantee that all of Quickly’s functions work, but after a few hours of hacking I at least have a pretty good start.  It’s not packaged yet, so to try it out you will need todo the following:

1. bzr branch lp:~mhall119/singlet/quickly-lens-template
2. sudo ln -s ./quickly-lens-template /usr/share/quickly/templates/singlet-lens
3. quickly create singlet-lens <your-lens-project-name>
4. cd <your-lens-project-name>
5. quickly package

Starting today at 1500 UTC, we’ll be conducting a series of online classes for Ubuntu Developer Week.  Whether you are interest in developing new applications for Ubuntu, or want to make an existing app take advantage of all of Ubuntu’s features, this is definitely something you should attend.

This cycle Daniel Holbach will kick things off with a overview of Ubuntu development, using Bazaar and Launchpad to collaborate both online and off with teams of developers all over the world.

After that I will be giving an overview of the unique collection of technologies and services that Ubuntu offers application developers, including Unity integration, Ubuntu One cloud storage, and the Software Center.  Then I will be joined by Micha? Sawicz to talk about Ubuntu TV, and how you can get a development environment setup and start hacking on it yourself

Later, David Callé and Michal Hruby will be showing you how to integrate with the Unity Dash by writing custom lenses and scopes for your content.  And if you are interested in that, be sure to come back Thursday for my session on writing simple lenses and scopes in Python using the Singlet library.

Mark Mims and Dustin Kirland will both by presenting on different ways Ubuntu lets you take advantage of the latest cloud technology to improve the development, testing and deployment of your application and stack.  And Stuart Langridge will be talking about the latest developments in the Ubuntu One Database (U1DB), and then showing how you can integrate our file and data syncing infrastructure into your own application.

You will also learn how to work upstream with Debian (both pulling changes in and sending them back), how to properly and easily package your application for distribution, and of course how to work on contributing changes back to Ubuntu itself.

If you have written or know how to write a Quickly template, I’d like to get some help making one for Singlet Lenses and Scopes.

I’ve finally had a little extra time to get back to working on Singlet.  There’s been a lot of progress since the first iteration.  To start with, Singlet had to be upgraded to work with the new Lens API introduced when Unity 5.0 landed in the Precise repos.  Luckily the Singlet API didn’t need to change, so any Singlet lenses written for Oneiric and Unity 4 will only need the latest Singlet to work in Precise[1].

The more exciting development, though, is that Singlet 0.2 introduces an API for Scopes.  This means you can write Lenses that support external scopes from other authors, as well as external Scopes for existing lenses.  They don’t both need to be based on Singlet either, you can write a Singlet scope for the Music Lens if you wanted to, and non-Singlet scopes can be written for your Singlet lens.  They don’t even have to be in Python.

In order to make the Scope API, I chose to convert my previous LoCo Teams Portal lens into a generic Community lens and separate LoCo Teams scope.  The Lens itself ends up being about as simple as can be:

from singlet.lens import Lens, IconViewCategory, ListViewCategory 

class CommunityLens(Lens): 

    class Meta:
        name = 'community'
        description = 'Ubuntu Community Lens'
        search_hint = 'Search the Ubuntu Community'
        icon = 'community.svg'
        category_order = ['teams', 'news', 'events', 'meetings']

    teams = IconViewCategory("Teams", 'ubuntu-logo')

    news = ListViewCategory("News", 'news-feed')

    events = ListViewCategory("Events", 'calendar')

    meetings = ListViewCategory("Meetings", 'applications-chat')

As you can see, it’s really nothing more that some meta-data and the categories.  All the real work happens in the scope:

class LocoTeamsScope(Scope):

    class Meta:
        name = 'locoteams'
        search_hint = 'Search LoCo Teams'
        search_on_blank = True
        lens = 'community'
        categories = ['teams', 'news', 'events', 'meetings']

    def __init__(self, *args, **kargs):
        super(LocoTeamsScope, self).__init__(*args, **kargs)
        self._ltp = locodir.LocoDirectory()
        self.lpusername = None

        if os.path.exists(os.path.expanduser('~/.bazaar/bazaar.conf')):
            try:
                import configparser
            except ImportError:
                import ConfigParser as configparser

            bzrconf = configparser.ConfigParser()
            bzrconf.read(os.path.expanduser('~/.bazaar/bazaar.conf'))

            try:
                self.lpusername = bzrconf.get('DEFAULT', 'launchpad_username')
            except configparser.NoOptionError:
                pass

    def search(self, search, model, cancellable):

I left out the actual search code, because it’s rather long and most of it isn’t important when talking about Singlet itself.  Just like the Lens API, a Singlet Scope uses an inner Meta class for meta-data.  The most important fields here are the ‘lens’ and ‘categories’ variables.  The ‘lens’ tells Singlet the name of the lens your scope is for.  Singlet uses this to build DBus names and paths, and also to know where to install your scope.  The ‘categories’ list will let you define a result item’s category using a descriptive name, rather than an integer.

 model.append('http://loco.ubuntu.com/events/%s/%s/detail/' % (team['lp_name'], tevent['id']), team['mugshot_url'], self.lens.events, "text/html", tevent['name'], '%s\n%s' % (tevent['date_begin'], tevent['description']), '')

It’s important that the order of the categories in the Scope’s Meta matches the order of categories defined in the Lens you are targeting, since in the end it’s still just the position number that’s being passed back to the Dash.

After all this, I still had a little bit of time left in the day.  And what good is supporting external scopes if you only have one anyway?  So I spent 30 minutes creating another scope, one that will read from the Ubuntu Planet news feed:

The next step is to add some proper packaging to get these into the Ubuntu Software Center, but you impatient users can get them either from their respective bzr branches, or try the preliminary packages from the One Hundred Scopes PPA.

[1] Note that while lenses written for Singlet 0.1 will work in Singlet 0.2 on Precise, the reverse is not necessarily true.  Singlet 0.2, as well as lenses and scopes written for it, will not work on Oneiric.

In an effort to increase the exposure of the work being done to improve the Unity desktop, we are moving discussions from the code-named #ayatana channel on freenode to the more discoverable #ubuntu-unity channel (still on freenode).  If you want to talk to Unity developers, find out what’s happening, or join the growing ranks of community contributors, this is a good place to start.

By now you should have heard that Canonical is branching out from the desktop and has begun work on getting Ubuntu on TVs.   Lost in all the discussion of OEM partnerships and content distribution agreements is a more exciting (from my perspective) topic: Ubuntu TV shows why Unity was the right choice for Canonical to make.

The Unity Platform

Ubuntu TV doesn’t just look like Unity, it is Unity.  A somewhat different configuration, visually, from the desktop version, but fundamentally the same.  Unity isn’t just a top panel and side launcher, it is a set of technologies and APIs: Indicators, Lenses, Quick Lists, DBus menus, etc.  All of those components will be the same in Ubuntu TV as they are on the desktop, even if their presentation to the user is slightly different.  When you see Unity on tablets and phones it will be the same story.

The Developer Story

Having the same platform means that Ubuntu offers developers a single development target, whether they are writing an application for the desktop, TVs, tablets or phones.  There is only one notifications API, only one search API, only one cloud syncing API.  Nobody currently offers that kind of unified development platform across all form factors, not Microsoft, not Google, not Apple.

If you are writing the next Angry Birds or TweetDeck, would you want to target a platform that only exists on one or two form factors, or one that will allow your application to run on all of them without having to be ported or rewritten?

The Consumer Story

Anybody with multiple devices has found an application for one that isn’t available for another.  How many times have we wanted the functionality offered by one of our desktop apps available to us when we’re on the go?  How many games do you have on your phone that you’d like to have on your laptop too?  With Ubuntu powered devices you will have what you want where you want it.  Combine that with Ubuntu One and your data will flow seamlessly between them as well.

A farewell to Gnome 2

None of this would have been possible with Gnome 2.  It was a great platform for it’s time, when there was a clear distinction between computers and other devices.  Computers had medium-sized screens, a keyboard and a mouse.  They didn’t have touchscreens, they didn’t change aspect ratio when turned sideways.  Devices lacked the ability to install third party applications, the mostly lacked network connectivity, and they had very limited storage and processing capabilities.

But now laptops and desktops have touch screens, phones have multi-core, multi-GHz processors.  TVs and automobiles are both getting smarter and gaining more and more of the features of both computers and devices.  And everything is connected to the Internet.  We need a platform for this post-2010 computing landscape, something that can be equally at home with a touch screen as it is with a mouse, with a 4 inch and a 42 inch display.

Unity is that platform.

Back when I first started writing Unity lenses, I lamented the complexity required to get even the most basic Lens written and running.  I wrote in that post about wanting to hide all of that unnecessary complexity.  Well now I am happy to announce the first step towards that end: Singlet.

In optics, a “singlet” is a very simple lens.  Likewise, the Singlet project aims to produce simple Unity lenses.  Singlet targets opportunistic programmers who want to get search results into Unity with the least amount of work.  By providing a handful of Python meta classes and base classes, Singlet lets you write a basic lens with a minimal amount of fuss. It hides all of the boilerplate code necessary to interface with GObject and DBus, leaving the developer free to focus solely on the purpose of their lens.  With Singlet, the only thing a Lens author really needs to provide is a single search function.

Writing a Singlet

So what does a Singlet Lens look like?  Here is a sample of the most basic lens, which produced the screenshot above:

#! /usr/bin/python

from singlet.lens import SingleScopeLens, IconViewCategory, ListViewCategory
from singlet.utils import run_lens

class TestLens(SingleScopeLens):

    class Meta:
        name = 'test'

    cat1 = IconViewCategory("Cat One", "stock_yet")

    cat2 = ListViewCategory("Cat Two", "hint")

    def search(self, phrase, results):
        results.append('http://google.com/search?q=%s' % phrase,
                             'file',
                             self.cat1,
                             "text/html",
                             phrase, phrase, '')

        results.append('http://google.com/search?q=%s' % phrase,
                             'file',
                             self.cat2,
                             "text/html",
                             phrase, phrase, '')

if __name__ == "__main__":
    import sys
    run_lens(TestLens, sys.argv)

As you can see, there isn’t much to it.  SingleScopeLens is the first base class provided by Singlet.  It creates an inner-scope for you, and connects it to the DBus events for handling a user’s search events.  The three things you need to do, as a Lens author, is give it a name in the Meta  class, define at least one Category, and most importantly implement your custom search(self, phrase, results) method.

Going Meta

Django developers will notice a similarity between Singlet Lenses and Django Models in their use of an inner Meta class.  In fact, they work exactly the same way, though with different properties.  At a minimum, you will need to provide a name for your lens.  Everything else can either use default values, or will be extrapolated from the name.  Everything in your Meta class, plus defaults and generated values, will be accessible in <your_class>._meta later on.

Categorically easy

Again borrowing from Django Models, you add categories to your Singlet Lens by defining it in the Class’s scope itself, rather than in the  __init__ method.  One thing that I didn’t like about Categories when writing my previous lenses was that I couldn’t reference them when adding search results to the result model.  Instead you have to give the numeric index of the category.  In Singlet, the variable name you used when defining the category is converted to the numeric index for that category, so you easily reference it again when building your search results.  But don’t worry, you category objects are still available to you in <your_class>._meta.categories if you want them.

The search is on

The core functionality of a Lens is the search.  So it makes sense that the majority of your work should happen here.  Singlet will call your search method, passing in the current search phrase and an empty results model.  From there, it’s up to you to collect data from whatever source you are targeting, and start populating that results model.

You can handle the URI

Unity knows how to handle common URIs in your results, such as file:// and http:// uris.  But often times your lens isn’t going to be dealing with results that map directly to a file or website.  For those cases, you need to hook into DBus again to handle the URI of a selected result item, and return a specifically constructed GObject response.  With Singlet, all you need to do is define a handle_uri method on your Lens, and it will take care of hooking it into DBus for you.  Singlet also provides a couple of helper methods for your return value, either hide_dash_response to hide the dash after you’ve handled the URI, or update_dash_response if you want to leave it open.

Make it go

Once you’ve defined your lens, you need to be able to initialize it and run it, again using a combination of DBus and GObject.  Singlet hides all of this behind the run_lens function in singlet.utils, which you should call at the bottom of your lens file as shown in the above snippet.

Lord of the files

There’s more to getting your Lens working that just the code, you also need to specify a .lens file describing your lens to Unity, and a .service file telling dbus about it.  Singlet helps you out here too, by providing command line helpers for generating and installing these files.  Suppose the code snippet above was in a file called testlens.py, once it’s written you can run “python testlens.py make” and it will write test.lens and unity-test-lens.service into your current directory.  The data in these files comes from <your_lens>._meta, including the name, dbus information, description and icon.  After running make you can run “sudo python testlens.py install”, this will copy your code and config files to where they need to be for Unity to pick them up and run them.

More to come

You can get the current Singlet code by branching lp:singlet.  I will be working on getting it built and available via PyPi and a PPA in the near future, but for now just having it on your PYTHONPATH is enough to get started using it.  Just be aware that if you make/install a Singlet lens, you need to make the Singlet package available on Unity’s PYTHONPATH as well or it won’t be able to run.  I’ve already converted my Dictionary Lens to use Singlet, and will work on others while I grow the collection of Singlet base classes.  If anybody has a common yet simple use case they would like me to target, please leave a description in the comments.

Unity certainly has been getting a lot of attention in the past year.  Love it or hate it, everybody seems to have something to say, whether it’s about the Launcher, application indicators, or the window control buttons being on the left.  But with all the talk about Unity, good and bad, one very unique aspect that hasn’t been getting nearly enough attention are Lenses.

Lenses are a central part of the Unity desktop, and anybody who’s used it will be familiar with the default Application and File lenses, maybe even the Music lens.  But there’s so much more to this technology than you might think.  In fact, David Callé has recently been spearheading an effort to build out a large number of small but incredibly useful lenses.  I first took notice of David’s work when he released his Book lens which, being a huge ebook fan, really brought home the usefulness of Unity Lenses for me.

More recently, David has been writing Scopes for the One Hundred Scopes project.  A Scope is the program that feeds results into a Lens.  While the Lens defines the categories and filters, it’s the Scopes that do the heavy lifting of finding and organizing the data that will ultimately be displayed on your Dash.  If you follow David on Google+, chances are you’ve seen him posting screenshots of one scope after another as he writes them, often multiple of them per day.

Seeing how quickly he was able to write these, I decided to dive in and try it out myself.  You can write Lenses in a variety of languages, including Python, my language of choice.  I decided to start of with something relatively easy, and something that I’ve personally been missing for a while.  I used to use a Gnome2 applet called Deskbar, which let you type in a short search word or phrase, and it presented you with search results and various other options.  Included among those was the option to lookup the word in the gnome-dictionary, and I used this option on a startlingly frequent basis.  Unfortunately Deskbar fell out of favor and development even before the switch to Gnome 3, and I’d been lacking a quick way to lookup words ever since.  So I decided that the Lens I wanted was one that would replace this missing functionality, a Dictionary lens.

My first task was to find out how to write a lens.  I checked the Ubuntu Wiki and the Unity portal, both of which offered a lot of technical information about writing lenses, but unfortunately not very much that I found helpful for someone just starting off.  In fact, I had to get a rather large amount of one-on-one help from David Callé before I could even get the most basic functionality working.

Lenses and Scopes all communicate with each other and with the Unity Dash via DBus, and for anybody not familiar with DBus this makes for a very steep learning curve.  On top of that, writing it in Python means you’ll be relying on GObject Introspection (GI), which is a very nice way of making APIs written in one language automatically available to another, but it also means you’re going to be using the lowest common denominator when it comes to language features.  I found that learning to work with these two technologies accounted for 90% or more of the time it took me to write my Dictionary lens.  Before I write another Lens or Scope, I plan on wrapping much of the DBus and GI boilerplate and wiring behind a simple, reusable set of Python classes.  I hope this will help developers, both newbies and seasoned Unity hackers, in writing simple Scopes by allowing them to focus 90% of their time on writing the code that does the actual searching.

But by the end of the day I had a working Dictionary lens.  It uses your local spellcheck dictionary, via python-enchant, to both confirm whether or not the word you typed in is spelled correctly, as well as offer a list of suggested alternatives.  I also dug through the gnome-dictionary code and found that it was pulling its definitions from the dict.org online database using an open protocol.  Using the python-dictclient I was able to query the same database, and include the start of a word’s definition in the Lens itself.

This lens turned out to be more complex than I had originally envisioned, not just for the features listed above, but also because I needed to override what happened when you clicked on an item.  When you build up your results, you have to give each item a unique URI, which is often in the form or an http:// or file:// URL that Gnome knows how to handle.  But for results that were just words, I needed to do the handling myself, which meant more DBus wiring to have the mouse click event call a local function.  From there I was able to copy the word to the Gnome clipboard or launch gnome-dictionary for viewing the full definition.

After seeing that first Lens running in my Dash, I felt an urge to try another.  Since I already had all of the DBus and GI code, I wouldn’t have to mess with all of that and I could focus just on the functionality I wanted.  Jorge Castro has been trying to get me to write a lens for the LoCo Teams Portal (formerly LoCo Directory) since the concept was first introduced to Unity under the name “Places”.  Since LTP already offers a REST/JSON api, this turned out to be remarkably simple to do.  Between the existing DBus/GI code copied from my previous lens, and an existing python client library for the LTP, I was able to get a working lens in only a couple of hours.

For item icons, you can use either a local icon, or a URL to a remote image.  For this lens, I used the team’s mugshot URL that LTP pulls from the team’s Launchpad information.  When you search, it’ll show matching Teams, as well as Events and Meetings for those teams, and any Event or Meeting that also matches your search criteria.  I’ve also added the ability for this lens to lookup your Launchpad username (by checking for it in your bazaar.conf) and defaulting it to display the LoCo Teams you are a member of, as well as their upcoming Events and Meetings.

Both the Dictionary Lens and the LTP Lens lump the Lens and Scope code in the same Python class, but it doesn’t have to be this way.  You can write a Scope for someone else’s Lens, and vice versa.  In fact, plan on separating the LTP lens into a general purpose Community Lens, with an LTP Scope feeding it results about LoCo Teams.  From there, others can write scopes pulling in other community information to be made available on the Dash.  This will also be my prototype for a Python-friendly wrapper around all of the DBus and GI work that scope writers probably don’t need to know about anyway.