== Dev Week -- libmessagingmenu -- larsu -- Wed, Aug 29th, 2012 == {{{#!irc [18:01] hi everyone [18:01] I'm Lars, I'll talk a bit about the changes we've made to the messaging menu this cycle [18:02] most importantly: libmessaging-menu, the new API for applications to integrate with the messaging menu [18:02] please don't hesitate to ask questions anytime [18:03] all the changes we've made have just landed in quantal a couple of days ago [18:03] for those of you already running quantal: that's the reason some apps show up in the menu right now ;) [18:04] let me just give a very short overview of the messaging menu [18:05] I assume most people here will be familiar with it [18:05] it's this little icon that sits in your panel, notifying you about incoming messages from various applications [18:05] also, it let's you set a global chat status for all apps at once [18:06] and it provides a way to launch messaging-related applications [18:06] up until now, three apps were always shown in the menu (Chat, Mail, and Broadcast) [18:07] starting from quantal, this will not be the case anymore: if no application is configured to show up in the menu, the menu will simply disappear [18:07] also, all applications will be referred to by their "real" name and icon, so Chat --> Empathy, Mail --> Thunderbird and Broadcast --> Gwibber [18:08] and ubuntu1 is gone from the messaging menu. It's not a messaging app anyway [18:09] if you're interested in why the menu works the way it is, there is a design specification with all the rationale at https://wiki.ubuntu.com/MessagingMenu [18:10] of course, we encourage application authors to integrate their apps with the menu [18:10] (where it makes sense of course ;) ) [18:11] !Q [18:11] ironhalik asked: With the new messaging menu, what's the situation with backward compatibility with Precise and older releases? Should I develop with Quantal or Precise in mind for largest userbase? [18:12] good question: the messaging menu in quantal is not backward compatible with the one in precise [18:12] we pondered keeping that, but it was more work than it was worth [18:13] to reach the biggest audience, you probably want to develop for precise, since that is the current release and it is an lts [18:14] if you think you have cutting edge users that will mostly be on the new version of ubuntu, I recommend going with the new API [18:14] it's much easier to use I am told ;) [18:14] ironhalik, does that answer your question? [18:16] so, each application gets a section in the messaging menu, which contains 3 types of items [18:16] (1) the application launcher itself, with a litte triangle next to it if the application is running [18:17] (2) shortcuts to commonly used actions (for example thunderbird has "Compose New Message" and "Contacts") [18:17] (3) the most important one: message source (for example, Thunderbird will add a menu entry for each mailbox that has new messages) [18:18] (1) and (2) are completely controlled by the applications .desktop file and cannot be changed while the application is running [18:19] to make the shortcut actions (2) that you have defined in the .desktop file appear in the messaging menu, the "TargetEnvironment" or "OnlyShowIn" keys must contain "Messaging Menu" [18:19] this is exactly the same way quicklists are handled for the launcher [18:20] so, let's go ahead with a concrete example of how to use libmessaging-menu [18:21] I'll paste a small python program line-by-line and explain what each line is doing [18:22] first: you need the gir1.2-messagingmenu-1.0 package, which is installed by default in quantal [18:22] as usual with gobject introspection, the first line of python is: [18:22] >>> from gi.repository import MessagingMenu, GLib [18:23] we'll need GLib later for the mainloop [18:23] as an aside: nothing will get send to the messaging menu until you run the main loop [18:24] next, you need to create a MessagingMenuApp object, which represents one application section in the menu [18:25] >>> mmapp = MessagingMenuApp(desktop_id="thunderbird.desktop") [18:25] you pass a desktop file id into the constructor, from which the items (1) and (2) I talked about earlier will be created [18:25] in this case, we're pretending to be thunderbird [18:26] to notify the messaging menu that our application is running, we call [18:26] >>> mmapp.register() [18:26] this does two things: if the application has never been in the menu before, a section will be created for it [18:27] and secondly, the application will be marked as "running" (with the little triangle next to it) [18:28] okay, now let's add a message source to the section: [18:29] >>> mmapp.append_source_with_count("inbox", None, "Inbox", 3) [18:29] this will append a new item with the label "Inbox" with a count of 3, which is shown on the right side of the menu item [18:30] the first parameter of this call is a unique identifier, the second one an optional icon (or None if you don't need one) [18:30] the third one is the label, and the fourth a count [18:30] analogous, there's also append_source_with_time, which you can pass a time stamp [18:31] the messaging menu will display the amount of time passed since that timestamp for these items [18:31] (for example, empathy uses that for incoming instant messages) [18:32] if you want the messaging menu envelope in the panel to turn blue, because the received notification is an important one: [18:32] >>> mmapp.draw_attention("inbox") [18:32] you just pass that function the id that we used to create the item [18:34] now, we want to get notified when the user selects the source and - for the sake of this example - simply print which source was activated [18:34] so we first need a small function [18:34] >>> def source_activated(mmapp, source_id): print id [18:34] sorry, that's "print source_id" of course [18:34] now, we can connect to the mmapp's "activate-source" signal [18:35] >>> mmapp.connect("activate-source", source_activated) [18:35] the source will be automatically removed when the user clicks on it [18:36] to try this out, let's spin up a main loop: [18:36] >>> GLib.MainLoop().run() [18:37] the messaging menu will automatically mark your application as "not running" when it stops running, no need to do anything [18:38] however, if you want to completly remove the application from the menu, call [18:38] >>> mmapp.unregister() [18:39] your application should remove any sources from the menu when the user gets to them in some other way [18:40] for example, when thunderbird is opened from the launcher and the user reads all messages that way [18:40] call mmapp.remove_source("inbox") to do this [18:40] there's not much more to it :) [18:41] unfortunately, I didn't manage to upload the API documentation in time for this talk, but it will appear on developer.ubuntu.com soon [18:41] and since it's a gobject-based library, your favorite programming language is most likely supported [18:41] hm, I've been talking all this time: are there any questions? [18:43] I've pasted our little example here: http://pastebin.ubuntu.com/1174375/ [18:50] There are 10 minutes remaining in the current session. [18:55] There are 5 minutes remaining in the current session. [18:55] marcosb asked: can i implement this example in ruby? [18:56] marcosb, to be honest, I'm not sure if there is gobject-introspection for ruby (ruby doesn't seem to be very popular amongst linux desktop programmers) [18:57] if there is, then you can implement this example in ruby [18:57] a quick google search seems to suggest that they exist [18:58] well, not many questions: hope you enjoyed it anyway. Bye! }}}