UnityLenses

Dev Week -- Unity Lenses! -- davidcalle & mhr3 -- Tue, Jan 31st, 2012

   1 [19:01] <davidcalle> Hello everyone, I'm David Callé
   2 [19:01] <mhr3> Hi there, i'm Michal Hruby
   3 [19:02] <davidcalle> We are going to introduce you to Unity lenses, how they work, what they do.
   4 [19:02] <davidcalle> And... most importantly, how to make them.
   5 [19:02] <mhr3> so let's get to it
   6 [19:03] <davidcalle> A lens is basically a plugin for the Dash. To display data to the user.
   7 [19:04] <davidcalle> And scopes are search engines for the lens, to bring the data.
   8 [19:04] <ClassBot> calmpitbull asked: What is the best way to get started with programing unity lenses and scopes
   9 [19:05] <mhr3> calmpitbull, you're just about to learn that :)
  10 [19:06] <davidcalle> A lens is mostly an architecture
  11 [19:07] <davidcalle> Categories and filters, used to guide the user through the data
  12 [19:07] <ClassBot> pawel_st asked: ​ I've asked this on one of the previous session, but maybe you can give a more detailed answer here... Why did you choose to have daemons for all lenses? Seems to lead to more and more resources usage as new lenses are added? Why not spawn lenses on demand, or do something similar to be more resource-friendly?
  13 [19:08] <mhr3> pawel_st, the reason is to be able to easily add and remove lenses
  14 [19:09] <mhr3> pawel_st, this way one can easily replace the default apps lens with something they like
  15 [19:09] <mhr3> or any other of course
  16 [19:09] <mhr3> and the default daemons are very light, so it shouldn't be an issue atm
  17 [19:10] <ClassBot> gaberlunzie asked: ​ are there any obstacles to lens displaying online data? My askubuntu lens turns up empty except for the "Ask a question" action ...
  18 [19:10] <davidcalle> There shouldn't be any obstacles. It just uses http calls.
  19 [19:11] <mhr3> gaberlunzie, perhaps a bug in the lens :)
  20 [19:11] <mhr3> feel free to file it
  21 [19:11] <ClassBot> pawel_st asked: ​ There is a nice initiative for simplifying lens/scopes development - Singlet project. Are there plans to make it available by default in Ubuntu? Or anything similar?
  22 [19:12] <mhr3> ok, so let's continue with the session
  23 [19:12] <davidcalle> Singlet is currently being turned into a Quickly template
  24 [19:13] <mhr3> once we have a lens that displays data in particular categories and provides filters, we implement scope(s) which provide data
  25 [19:14] <mhr3> a couple of guidelines about when to implement lenses vs scopes can be found at https://wiki.ubuntu.com/Unity/Lenses/Guidelines
  26 [19:14] <mhr3> but let's make this more fun and actually look at a sample lens and scope
  27 [19:14] <mhr3> the unity-lens-sample project on Launchpad has a couple of these available (https://code.launchpad.net/unity-lens-sample/)
  28 [19:15] <mhr3> so I suppose everyone likes python, so let's take a look at that one
  29 [19:15] <mhr3> if you want to get it, run `bzr branch lp:~unity-team/unity-lens-sample/python-5.0`
  30 [19:16] <mhr3> the 5.0 indicates that this lens is for libunity-5.0 (which is in precise)
  31 [19:16] <mhr3> if you're on oneiric and dont have unity ppas enabled, 4.0 is for you
  32 [19:17] <mhr3> so, http://bazaar.launchpad.net/~unity-team/unity-lens-sample/python-5.0/view/head:/unity-lens-sample is the lens code
  33 [19:17] <mhr3> and david as the author will explain details :)
  34 [19:18] <davidcalle> As you can see, the lens code is quite small.
  35 [19:18] <ClassBot> fantasti1001 asked: what programming language do i need to know to make lenses?
  36 [19:18] <davidcalle> The first important thing is to declare your lens:
  37 [19:18] <davidcalle> BUS_NAME = "net.launchpad.lens.sample"
  38 [19:19] <mhr3> fantasti1001, you can pick python / c / vala (or javascript experimentally)
  39 [19:19] <davidcalle> The name is rather arbitrary, but it illustrates the purpose of the lens
  40 [19:19] <davidcalle> fantasti1001, Python, C, Vala, and even Javascript now (which is rather experimental)
  41 [19:20] <davidcalle> Then, we define a few constants for the lens:
  42 [19:20] <ClassBot> AlanBell asked: will there be an "accounts" dialog or something for lenses that require authentication credentials to be entered (a bit like Empathy or Gwibber has)
  43 [19:20] <davidcalle> It's dbus path : self._lens = Unity.Lens.new ("/net/launchpad/lens/sample", "sample")
  44 [19:21] <davidcalle> We also want to define the search hint (the text in the empty search bar)
  45 [19:21] <davidcalle> self._lens.props.search_hint = "Search"
  46 [19:21] <mhr3> AlanBell, that's up to the individual apps right now, ideally they'd integrate with the system's "online account"
  47 [19:22] <davidcalle> We can also choose to have the lens icon visible in the search bar. If not, it will still be available via its shortcut.
  48 [19:22] <davidcalle> self._lens.props.visible = True;
  49 [19:22] <davidcalle> Then, one of the most important thing is to have the lens visible in the Home Dash.
  50 [19:22] <davidcalle> Or not.
  51 [19:22] <davidcalle>            self._lens.props.search_in_global = True;
  52 [19:23] <davidcalle> If you are looking at the code right now (http://bazaar.launchpad.net/~unity-team/unity-lens-sample/python-5.0/view/head:/unity-lens-sample)
  53 [19:23] <davidcalle> You can see, that we also define the categories, which have a name, an icon, and a renderer.
  54 [19:24] <davidcalle> The renderer is the way the Dash will display the results.
  55 [19:24] <mhr3> you can see all the properties here http://developer.ubuntu.com/api/ubuntu-12.04/python/Unity-5.0.html#Unity.Lens
  56 [19:25] <davidcalle> Two renderers are currently available : the "vertical" and the "horizontal", they both display an icon, and a text for each result. But the horizontal can also dsiaply a second text called the comment.
  57 [19:26] <davidcalle> Here, I've defined two categories, using a different renderer.
  58 [19:26] <davidcalle> The filters are next on our list of things to define. You can find a list in the code.
  59 [19:27] <davidcalle> http://imagebin.org/index.php?mode=image&id=196573
  60 [19:27] <mhr3> there you can see the various renderers in action ^^
  61 [19:27] <davidcalle> Here is a screenshot of our sample lens, using the two renderers (the second one is hidden at the bottom)
  62 [19:29] <davidcalle> Now that we have a lens. We need a scope to provide the data.
  63 [19:29] <mhr3> right, but before that, please notice some of the system necessities for getting lens running
  64 [19:30] <mhr3> at the bottom of the lens sample you can see requesting DBus name
  65 [19:30] <mhr3> you need to do this, so unity can talk to the lens
  66 [19:30] <mhr3> and the name need to be equal to what you .lens file says
  67 [19:30] <mhr3> more details on that can be found at https://wiki.ubuntu.com/Unity/Lenses
  68 [19:30] <mhr3> or https://wiki.ubuntu.com/mhr3/Lenses (for the latest 5.0 version)
  69 [19:31] <mhr3> and now, let's take a look at the scope
  70 [19:31] <mhr3> so here we have it > http://bazaar.launchpad.net/~unity-team/unity-lens-sample/python-5.0/view/head:/unity-scope-wikipedia
  71 [19:32] <mhr3> this is an example of remote scope, that doesn't live directly inside the lens, but is an external process
  72 [19:32] <mhr3> you can create scope for any existing lens by just adding your .scope file into the lens directory
  73 [19:32] <mhr3> more on that again at the wiki mentioned earlier
  74 [19:32] <mhr3> but let's look at the code
  75 [19:33] <mhr3> commonality is again the requesting of dbus name, which is necessary for remote scopes
  76 [19:33] <mhr3> but doesn't need to be there for internal lens scopes
  77 [19:34] <mhr3> and then you just create a Scope instance ->
  78 [19:34] <mhr3> self.scope = Unity.Scope.new ("/net/launchpad/scope/information/wikipedia")
  79 [19:34] <mhr3> you specify a few properties again
  80 [19:34] <mhr3> like the search-in-global etc
  81 [19:34] <mhr3> (full list http://developer.ubuntu.com/api/ubuntu-12.04/python/Unity-5.0.html#Unity.Scope)
  82 [19:35] <mhr3> and most importantly you connect to the search-changed signal
  83 [19:35] <mhr3> self.scope.connect ("search-changed", self.on_search_changed)
  84 [19:35] <mhr3> this mean that everytime the user changes the search string this method will be invoked
  85 [19:35] <mhr3> and it's where you should do the actual search
  86 [19:36] <mhr3> the signal has a couple of parameters:
  87 [19:36] <mhr3> def on_search_changed (self, scope, search, search_type, cancellable):
  88 [19:36] <mhr3> important is the search, which is a LensSearch instance
  89 [19:36] <mhr3> http://developer.ubuntu.com/api/ubuntu-12.04/python/Unity-5.0.html#Unity.LensSearch
  90 [19:37] <mhr3> and this holds the data about the search
  91 [19:37] <mhr3> like the actual search_string
  92 [19:37] <mhr3> the scopes have a two results models which you need to update during the search
  93 [19:38] <mhr3> the correct results model is always stored in search.results_model
  94 [19:38] <mhr3> as you can see in http://bazaar.launchpad.net/~unity-team/unity-lens-sample/python-5.0/view/head:/unity-scope-wikipedia#L33
  95 [19:38] <ClassBot> pawel_st asked: ​ Is caching results of lens search possible via the framework, or is this something one needs to implement for his lens?
  96 [19:39] <mhr3> depends what you want to do
  97 [19:39] <mhr3> results from previous search are always available in the model
  98 [19:40] <mhr3> that's why you see model.clear() call here http://bazaar.launchpad.net/~unity-team/unity-lens-sample/python-5.0/view/head:/unity-scope-wikipedia#L35
  99 [19:40] <mhr3> so it's up to you how are you going to use that
 100 [19:41] <mhr3> so once we get results for the query the user wants, we append those to the model
 101 [19:41] <mhr3> as you can see in http://bazaar.launchpad.net/~unity-team/unity-lens-sample/python-5.0/view/head:/unity-scope-wikipedia#L81
 102 [19:42] <mhr3> the models we are talking about are part of the Dee library (see it's reference @ http://developer.ubuntu.com/api/ubuntu-12.04/python/Dee-1.0.html )
 103 [19:42] <mhr3> and there's a specific data the model expects
 104 [19:42] <mhr3> for results it's uri, icon, category id, mimetype, display name, comment and dnd_uri
 105 [19:43] <mhr3> so you add results to the model and once you're done, you just call search.finished() on the LensSearch instance
 106 [19:44] <mhr3> the user can then click on any of results
 107 [19:44] <mhr3> and if you picked some standard uri (like http://...) unity can just launch it in the browser for example
 108 [19:44] <mhr3> but if your lens is doing something special
 109 [19:45] <mhr3> you can use your own uris, and if you connect to the activate_uri signal of the scope you'll be notified when the user activated them, so you can do whatever you want
 110 [19:45] <mhr3> and that's the basics
 111 [19:45] <mhr3> questions?
 112 [19:46] <ClassBot> kanliot asked: do lenses require unity and ubuntu?
 113 [19:46] <davidcalle> They do.
 114 [19:46] <davidcalle> Not Ubuntu, but at least Unity.
 115 [19:46] <mhr3> well unity is what controls them
 116 [19:46] <mhr3> you could implement your own ui
 117 [19:46] <mhr3> but there's nothing in existence that would do that
 118 [19:47] <mhr3> not that i know of anyway :)
 119 [19:47] <davidcalle> If you want to look at various code examples
 120 [19:48] <davidcalle> https://code.launchpad.net/onehundredscopes
 121 [19:48] <davidcalle> It's a lot of scopes and lenses branches, doing very different things, from talking to web API, to looking into user folders.
 122 [19:48] <mhr3> if you're wondering about the changes that were made in latest Unity-5.0 (and therefore really advanced stuff) feel free to look at http://www.grillbar.org/wordpress/?p=585
 123 [19:49] <ClassBot> Ceno asked: is there any difference in performance between the various languages we can program lens/scopes in?
 124 [19:50] <ClassBot> There are 10 minutes remaining in the current session.
 125 [19:51] <mhr3> Ceno, good question
 126 [19:51] <mhr3> we dont really have any scientific data to suggest one way or the other
 127 [19:52] <mhr3> of course theoretically languages that don't need garbage collector and such things ought to be faster :)
 128 [19:52] <mhr3> but mostly the slowest part of lens is talking to a webservice which is slow anyway :)
 129 [19:52] <mhr3> if they are talking to a webservice of course :)
 130 [19:52] <ClassBot> mfisch asked: is there a recommended IRC channel where lens-writers can discuss things?
 131 [19:53] <davidcalle> #ubuntu-unity is the place for that
 132 [19:53] <mhr3> mfisch, ^^ thats the place
 133 [19:53] <ClassBot> Ceno asked: I might have missed something, and if I did I apologize, but how do you go from these 2 pieces of code, one for lens one for scope, to actually testing the thing live in Unity?
 134 [19:54] <mhr3> there's a README file in the directory ;)
 135 [19:54] <mhr3> basically you copy the .lens and .scope files to specific directories and restart unity
 136 [19:55] <mhr3> http://bazaar.launchpad.net/~unity-team/unity-lens-sample/python-5.0/view/head:/README
 137 [19:55] <davidcalle> A lens daemon comes with a .lens files, the scope daemon with a .scope file. Their content is pretty much self explicit.
 138 [19:55] <davidcalle> s/files/file
 139 [19:55] <ClassBot> There are 5 minutes remaining in the current session.
 140 [19:56] <davidcalle> They both need to go in /usr/share/unity/lenses/<lens name>
 141 [19:56] <davidcalle> The daemons can be anywhere.
 142 [19:56] <davidcalle> An important thing :
 143 [19:57] <davidcalle> To start a new lens. You need to restart unity (unity --restart or setsid unity)
 144 [19:57] <davidcalle> Just once, to make it learn about the new lens.
 145 [19:58] <ClassBot> mhall119 asked: once I have a lens or scope, how do I get it into Software Center?
 146 [19:58] <davidcalle> But for the scopes, you just need to restart the lens daemon.
 147 [19:59] <mhr3> i'm afraid we won't cover software center in this session
 148 [19:59] <ClassBot> jincreator asked: Is it possible to extract and use lens at user's home directory, not /usr/share/... ?
 149 [19:59] <davidcalle> mhall119, you package your lens, then submit the package to https://myapps.developer.ubuntu.com
 150 [20:00] <mhr3> jincreator, unfortunately not, unity only checks /usr/share/unity/lenses directory
 151 [20:00] <mhr3> Ok, seems like we're out of time, thanks everyone for attending!
 152 

MeetingLogs/devweek1201/UnityLenses (last edited 2012-02-01 11:18:44 by dholbach)