== Making your app appear in the Indicators - Instructors: tedg == {{{#!irc [19:00] Logs for this session will be available at http://irclogs.ubuntu.com/2011/09/08/%23ubuntu-classroom.html following the conclusion of the session. [19:01] Howdy folks. [19:02] My name is Ted and I work at the Canonical Desktop Experience team. [19:02] Specifically I work with the various indicators, I like to joke that "I control the upper right corner of your screen" ;-) [19:02] But, that's really not the case. [19:03] Really what we do is expose the functionality that is in the system to the user. [19:03] *and* probably more importantly, the information that comes from applications. [19:03] This session is about getting that information out of the applications and handing it up to the indicators. [19:04] We're going to cover quickly a few different ways, and then I'll take questions as long as you guys have 'em to go more in depth. [19:04] Specifically, I'm going to cover messaging menu, application indicator and the sound menu. [19:04] So, let's get started. [19:05] I'm going to start with the messaging menu because it's the oldest (and I couldn't figure out any other ordering that made sense) [19:05] The spec for the messaging menu is here: https://wiki.ubuntu.com/MessagingMenu [19:05] I think what makes the most sense to look there is at the rationale. [19:05] It's a menu that is designed to handle human-to-human communication in an aggregated way. [19:06] It's like you communicate with people in a variety of ways, but not all of those need icons on your panel. [19:06] So if you're looking at an application that does that, how do you integrate? [19:06] You use libindicate, which allows your application to indicate on dbus that you have messages. [19:07] libindicate hides all the dbus stuff, so you don't need to worry about that, it's more about representing the info you have. [19:07] So where is it? The source for the library itself is at http://launchpad.net/libindicate [19:07] It has both the client and the server, but chances are you'll only need one of those. [19:07] And that's the server. [19:08] The client is used by the menu itself, and put into a single library so they always remain consistent [19:08] Let's look at an example in Python: http://bazaar.launchpad.net/~indicator-applet-developers/libindicate/trunk/view/head:/examples/im-client.py#L58 [19:08] This is a simple "IM Client" [19:09] thought it really only makes a single entry in the messaging menu. [19:09] And it tells the messaging menu that it's really Empathy. [19:09] I don't recommend lying in your code :-) [19:10] As we look at that example you can see that the code grabs the default server and sets some properties on it. [19:10] The most significant here is the desktop file as we use that to get a bunch of information like the icon and name of the application out of there. [19:10] Your application probably already has a desktop file, just throw the path to it in there. [19:11] Then it creates an indicator. These are the items under your application in the messaging menu. [19:11] This one is a time based one as you see the time gets set there. [19:11] But there can also be count based for applications like e-mail programs that have mailboxes. [19:12] There are design guide lines for how various applications should integrate. [19:12] https://wiki.ubuntu.com/MessagingMenu#How_applications_should_integrate_with_the_messaging_menu [19:12] Obviously that doesn't cover all applications, but it should be enough to get you started. [19:13] You can also set properties like whether the envelope changes color or not as well. [19:13] And sort the various items. [19:14] There is also the ability to put custom menu items on the menu, but I'm not going to go into that today unless there are some questions. [19:14] Second up is application indicators. [19:14] You can find out some about the design of those guys here: https://wiki.ubuntu.com/DesktopExperienceTeam/ApplicationIndicators [19:15] And a bit about their rationale. [19:15] One of the things that they're targeting is allowing applications that are long running and need to put status of some type on the panel, to do so in a consistent way. [19:15] The way that we've chose is an icon (possibly with a label) and a menu. [19:16] This allows the entire top of the screen to behave like a menu bar. [19:16] Application indicators are based on the KDE Status Notifier Item spec, but to create one you can just use libappindicator. [19:17] http://launchpad.net/libappindicator/ [19:17] This is a small library that implements the KSNI spec over dbus and provides an easy way to support it in your application. [19:17] It also provides an internal fallback to using the status area on desktops that don't support KSNI. [19:17] So you don't have to do that fallback in your application manually. [19:18] For those who are already familiar with libappindicator, we've got some new features this cycle. === tyler is now known as Guest71989 [19:18] First off, it's now it's own library. Which will hopefully ease its adoption by other distros. [19:19] There's no need to pull in the entire indicator stack just for providing libappindicator. [19:19] We're also supporting actions on middle click. [19:19] This is a tricky one, as we don't want to create undiscoverable functionality. [19:19] So what we've done is allow for a menu item that's already in the menu to be specified to receive middle click events. [19:20] This way that functionality is always available, and visible, to the user. [19:20] But power users can get some quick access to it if they choose. [19:20] We have some design guidlines for the app indicators. [19:20] https://wiki.ubuntu.com/CustomStatusMenuDesignGuidelines [19:21] The important thing to remember, is that app indicators aren't the end all be all of what you want. [19:21] There's been a long tradition in computing of doing stuff like this for every application, but that doesn't mean it's right :-) [19:21] We'd love it if people would integrate with the other category indicators (messaging, sound, etc.) before building their own. [19:21] Also, for many applications, launcher integration makes more sense. [19:22] (I believe Jason just talked about that, no?) [19:22] So remember all of those options before you choose an applicaiton indicator [19:22] Now, if you do, it's easy to do :-) [19:23] Here's a simple client, that does everything possible (except middle click) http://bazaar.launchpad.net/~indicator-applet-developers/libappindicator/trunk/view/head:/example/simple-client-vala.vala [19:23] Now it's a bit more complex than you need really. [19:23] As it has dynamic items and changes status, but it does show you the full spectrum of possibilities. [19:24] There's a C version as well [19:24] http://bazaar.launchpad.net/~indicator-applet-developers/libappindicator/trunk/view/head:/example/simple-client.c [19:24] The most important part is here: [19:24] http://bazaar.launchpad.net/~indicator-applet-developers/libappindicator/trunk/view/head:/example/simple-client.c#L160 [19:24] Where it creates the new object. [19:24] It has a name and an icon. [19:25] And a category. [19:25] Then you build up a standard GTK menu, and you set it here: http://bazaar.launchpad.net/~indicator-applet-developers/libappindicator/trunk/view/head:/example/simple-client.c#L226 [19:25] Your menu doesn't need to be as long. [19:25] But it's neat to see the things you can do there. [19:25] As far as signals go, you can just attach to the standard GTK ones on the menu items. [19:26] libappindicator will synthesize them for you. [19:26] So there's nothing to learn other than standard GTK menus. [19:27] So while the example is longer, there's only those two critical spots. [19:27] Okay, just checking my notes... think I got everything :-) [19:28] Last up is the newest in our bunch, the sound menu. [19:29] The sound menu takes care of all your sound related stuff. [19:29] Again it uses a standard protocol, MPRIS, but we've provided a smaller library that implements the critical functionality. [19:29] In this case, it is a couple of interfaces in libunity. [19:29] http://launchpad.net/libunity [19:30] There's no need for you to learn DBus or MPRIS, you can ust use the MusicPlayer interface there. [19:30] http://bazaar.launchpad.net/~unity-team/libunity/trunk/view/head:/src/unity-sound-menu.vala#L61 [19:30] It provides your basic setting of playlists and getting signals for play/pause/next/prev type controls. [19:31] So as soon as you set up one of those objects, your application will get a full music player control in the sound menu. [19:31] Just like Rhythmbox or Banshee. [19:31] It doesn't matter if you're getting the sound off the web, or local files, or how you get the music. [19:31] That's up to you :-) [19:32] Let's look at an example [19:32] here's a "TypicalPlayer" object [19:32] http://bazaar.launchpad.net/~unity-team/libunity/trunk/view/head:/test/vala/test-mpris-backend-server.vala#L23 [19:32] You can see how it sets the metadata for the song [19:33] And even the album art [19:33] And create a playlist as well. [19:33] The typical player then sets up signals for the various buttons. [19:33] This is part of the test suite, so it doesn't implement all of the backend for this. [19:34] But it provides a good show of how you can connect into the object. [19:34] You'll also see on line 56: http://bazaar.launchpad.net/~unity-team/libunity/trunk/view/head:/test/vala/test-mpris-backend-server.vala#L56 [19:34] That it builds a small menu for custom items like setting your preference for the song. [19:34] This can help with something like a Pandora client, where we want more information quickly available to the user. [19:35] These are standard menu items so you can make them check boxes, radio buttons, or what ever you wish. [19:35] There's not a whole lot of magic there, but that's largely because libunity takes care of all of that for you :-) [19:36] Lastly, I wanted to talk about the TODO list a little if this interested you but you didn't have an application specifically that you wanted to work on. [19:36] One of the big things that we did in this cycle was ensure that we had GObject Introspection bindings for all the indicator libs. [19:37] We'd like to drop all the hand coded ones. [19:37] But to do that we need all the applications currently using them in non-C languages to port over. [19:37] So if you're interested in helping out, we'd love some help there. [19:37] Also, we need to port the various examples over to using the GI bindings. [19:38] To make it easier for new people coming in to using them. [19:38] So, that's the end of my notes on the various ways for applications to integrate with the indicators. [19:39] I hope that gives everyone a good introduction to the possibilities [19:39] Does anyone have questions or want me to dive deeper into any of the topics? [19:41] Great! Thanks everyone. [19:42] Come grab me in #ayatana if you think of anything later }}}