== Dev Week -- Unity Lenses! -- davidcalle & mhr3 -- Tue, Jan 31st, 2012 == {{{#!irc [19:01] Hello everyone, I'm David Callé [19:01] Hi there, i'm Michal Hruby [19:02] We are going to introduce you to Unity lenses, how they work, what they do. [19:02] And... most importantly, how to make them. [19:02] so let's get to it [19:03] A lens is basically a plugin for the Dash. To display data to the user. [19:04] And scopes are search engines for the lens, to bring the data. [19:04] calmpitbull asked: What is the best way to get started with programing unity lenses and scopes [19:05] calmpitbull, you're just about to learn that :) [19:06] A lens is mostly an architecture [19:07] Categories and filters, used to guide the user through the data [19:07] 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? [19:08] pawel_st, the reason is to be able to easily add and remove lenses [19:09] pawel_st, this way one can easily replace the default apps lens with something they like [19:09] or any other of course [19:09] and the default daemons are very light, so it shouldn't be an issue atm [19:10] gaberlunzie asked: ​ are there any obstacles to lens displaying online data? My askubuntu lens turns up empty except for the "Ask a question" action ... [19:10] There shouldn't be any obstacles. It just uses http calls. [19:11] gaberlunzie, perhaps a bug in the lens :) [19:11] feel free to file it [19:11] 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? [19:12] ok, so let's continue with the session [19:12] Singlet is currently being turned into a Quickly template [19:13] once we have a lens that displays data in particular categories and provides filters, we implement scope(s) which provide data [19:14] a couple of guidelines about when to implement lenses vs scopes can be found at https://wiki.ubuntu.com/Unity/Lenses/Guidelines [19:14] but let's make this more fun and actually look at a sample lens and scope [19:14] the unity-lens-sample project on Launchpad has a couple of these available (https://code.launchpad.net/unity-lens-sample/) [19:15] so I suppose everyone likes python, so let's take a look at that one [19:15] if you want to get it, run `bzr branch lp:~unity-team/unity-lens-sample/python-5.0` [19:16] the 5.0 indicates that this lens is for libunity-5.0 (which is in precise) [19:16] if you're on oneiric and dont have unity ppas enabled, 4.0 is for you [19:17] so, http://bazaar.launchpad.net/~unity-team/unity-lens-sample/python-5.0/view/head:/unity-lens-sample is the lens code [19:17] and david as the author will explain details :) [19:18] As you can see, the lens code is quite small. [19:18] fantasti1001 asked: what programming language do i need to know to make lenses? [19:18] The first important thing is to declare your lens: [19:18] BUS_NAME = "net.launchpad.lens.sample" [19:19] fantasti1001, you can pick python / c / vala (or javascript experimentally) [19:19] The name is rather arbitrary, but it illustrates the purpose of the lens [19:19] fantasti1001, Python, C, Vala, and even Javascript now (which is rather experimental) [19:20] Then, we define a few constants for the lens: [19:20] 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) [19:20] It's dbus path : self._lens = Unity.Lens.new ("/net/launchpad/lens/sample", "sample") [19:21] We also want to define the search hint (the text in the empty search bar) [19:21] self._lens.props.search_hint = "Search" [19:21] AlanBell, that's up to the individual apps right now, ideally they'd integrate with the system's "online account" [19:22] We can also choose to have the lens icon visible in the search bar. If not, it will still be available via its shortcut. [19:22] self._lens.props.visible = True; [19:22] Then, one of the most important thing is to have the lens visible in the Home Dash. [19:22] Or not. [19:22] self._lens.props.search_in_global = True; [19:23] 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) [19:23] You can see, that we also define the categories, which have a name, an icon, and a renderer. [19:24] The renderer is the way the Dash will display the results. [19:24] you can see all the properties here http://developer.ubuntu.com/api/ubuntu-12.04/python/Unity-5.0.html#Unity.Lens [19:25] 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. [19:26] Here, I've defined two categories, using a different renderer. [19:26] The filters are next on our list of things to define. You can find a list in the code. [19:27] http://imagebin.org/index.php?mode=image&id=196573 [19:27] there you can see the various renderers in action ^^ [19:27] Here is a screenshot of our sample lens, using the two renderers (the second one is hidden at the bottom) [19:29] Now that we have a lens. We need a scope to provide the data. [19:29] right, but before that, please notice some of the system necessities for getting lens running [19:30] at the bottom of the lens sample you can see requesting DBus name [19:30] you need to do this, so unity can talk to the lens [19:30] and the name need to be equal to what you .lens file says [19:30] more details on that can be found at https://wiki.ubuntu.com/Unity/Lenses [19:30] or https://wiki.ubuntu.com/mhr3/Lenses (for the latest 5.0 version) [19:31] and now, let's take a look at the scope [19:31] so here we have it > http://bazaar.launchpad.net/~unity-team/unity-lens-sample/python-5.0/view/head:/unity-scope-wikipedia [19:32] this is an example of remote scope, that doesn't live directly inside the lens, but is an external process [19:32] you can create scope for any existing lens by just adding your .scope file into the lens directory [19:32] more on that again at the wiki mentioned earlier [19:32] but let's look at the code [19:33] commonality is again the requesting of dbus name, which is necessary for remote scopes [19:33] but doesn't need to be there for internal lens scopes [19:34] and then you just create a Scope instance -> [19:34] self.scope = Unity.Scope.new ("/net/launchpad/scope/information/wikipedia") [19:34] you specify a few properties again [19:34] like the search-in-global etc [19:34] (full list http://developer.ubuntu.com/api/ubuntu-12.04/python/Unity-5.0.html#Unity.Scope) [19:35] and most importantly you connect to the search-changed signal [19:35] self.scope.connect ("search-changed", self.on_search_changed) [19:35] this mean that everytime the user changes the search string this method will be invoked [19:35] and it's where you should do the actual search [19:36] the signal has a couple of parameters: [19:36] def on_search_changed (self, scope, search, search_type, cancellable): [19:36] important is the search, which is a LensSearch instance [19:36] http://developer.ubuntu.com/api/ubuntu-12.04/python/Unity-5.0.html#Unity.LensSearch [19:37] and this holds the data about the search [19:37] like the actual search_string [19:37] the scopes have a two results models which you need to update during the search [19:38] the correct results model is always stored in search.results_model [19:38] as you can see in http://bazaar.launchpad.net/~unity-team/unity-lens-sample/python-5.0/view/head:/unity-scope-wikipedia#L33 [19:38] pawel_st asked: ​ Is caching results of lens search possible via the framework, or is this something one needs to implement for his lens? [19:39] depends what you want to do [19:39] results from previous search are always available in the model [19:40] 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 [19:40] so it's up to you how are you going to use that [19:41] so once we get results for the query the user wants, we append those to the model [19:41] as you can see in http://bazaar.launchpad.net/~unity-team/unity-lens-sample/python-5.0/view/head:/unity-scope-wikipedia#L81 [19:42] 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 ) [19:42] and there's a specific data the model expects [19:42] for results it's uri, icon, category id, mimetype, display name, comment and dnd_uri [19:43] so you add results to the model and once you're done, you just call search.finished() on the LensSearch instance [19:44] the user can then click on any of results [19:44] and if you picked some standard uri (like http://...) unity can just launch it in the browser for example [19:44] but if your lens is doing something special [19:45] 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 [19:45] and that's the basics [19:45] questions? [19:46] kanliot asked: do lenses require unity and ubuntu? [19:46] They do. [19:46] Not Ubuntu, but at least Unity. [19:46] well unity is what controls them [19:46] you could implement your own ui [19:46] but there's nothing in existence that would do that [19:47] not that i know of anyway :) [19:47] If you want to look at various code examples [19:48] https://code.launchpad.net/onehundredscopes [19:48] It's a lot of scopes and lenses branches, doing very different things, from talking to web API, to looking into user folders. [19:48] 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 [19:49] Ceno asked: is there any difference in performance between the various languages we can program lens/scopes in? [19:50] There are 10 minutes remaining in the current session. [19:51] Ceno, good question [19:51] we dont really have any scientific data to suggest one way or the other [19:52] of course theoretically languages that don't need garbage collector and such things ought to be faster :) [19:52] but mostly the slowest part of lens is talking to a webservice which is slow anyway :) [19:52] if they are talking to a webservice of course :) [19:52] mfisch asked: is there a recommended IRC channel where lens-writers can discuss things? [19:53] #ubuntu-unity is the place for that [19:53] mfisch, ^^ thats the place [19:53] 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? [19:54] there's a README file in the directory ;) [19:54] basically you copy the .lens and .scope files to specific directories and restart unity [19:55] http://bazaar.launchpad.net/~unity-team/unity-lens-sample/python-5.0/view/head:/README [19:55] A lens daemon comes with a .lens files, the scope daemon with a .scope file. Their content is pretty much self explicit. [19:55] s/files/file [19:55] There are 5 minutes remaining in the current session. [19:56] They both need to go in /usr/share/unity/lenses/ [19:56] The daemons can be anywhere. [19:56] An important thing : [19:57] To start a new lens. You need to restart unity (unity --restart or setsid unity) [19:57] Just once, to make it learn about the new lens. [19:58] mhall119 asked: once I have a lens or scope, how do I get it into Software Center? [19:58] But for the scopes, you just need to restart the lens daemon. [19:59] i'm afraid we won't cover software center in this session [19:59] jincreator asked: Is it possible to extract and use lens at user's home directory, not /usr/share/... ? [19:59] mhall119, you package your lens, then submit the package to https://myapps.developer.ubuntu.com [20:00] jincreator, unfortunately not, unity only checks /usr/share/unity/lenses directory [20:00] Ok, seems like we're out of time, thanks everyone for attending! }}}