Ubuntu Wiki

   1 [21:01] <dpm> Next up is tedg_, the person who knows all about indicators, and who'll be thrilled to tell you how to add them to your applications
   2 === ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - https://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Questions in #ubuntu-classroom-chat || Event: Ubuntu App Developer Week - Current Session: Adding Indicator Support to Your Apps - Instructors: tedg
   3 [21:01] <ClassBot> Logs for this session will be available at http://irclogs.ubuntu.com/2011/04/14/%23ubuntu-classroom.html following the conclusion of the session.
   4 === tedg_ is now known as tedg
   5 [21:10] <tedg> Voice?
   6 [21:10] <tedg> Woot!
   7 [21:10] <tedg> Thanks Pendulum!
   8 [21:10] <tedg> Hey everyone, sorry about the delay.
   9 [21:10] <tedg> So my name is Ted Gould and I work with application indicators.
  10 [21:11] <tedg> Application indicators are menus that appear in the Unity panel and represent various applications.
  11 [21:11] <tedg> These, in general, shouldn't be used just because your project's logo is so cool.  Users. hate. that.
  12 [21:12] <tedg> But, it's more designed as a feature for long running applications, those that are more services to users, to expose that functionality.
  13 [21:12] <tedg> A good example of this would be Tomboy, so you can use your notes all the time and keep it running.
  14 [21:12] <tedg> Which is definitely useful.
  15 [21:13] <tedg> There's a set of design guidelines for using the app indicators.
  16 [21:13] <tedg> And that is here: https://wiki.ubuntu.com/CustomStatusMenuDesignGuidelines
  17 [21:13] <tedg> It goes through the various features and what the layout should be.
  18 [21:14] <tedg> If you've got any questions whether or not something should be an appindicator, that'd be a good place to get started.
  19 [21:14] <tedg> I'm not going to dwell on that though, as this is Dev week, so let's assume that you're application *really* needs an appindicator :-)
  20 [21:15] <tedg> For most applications that involves using libappindicator
  21 [21:15] <tedg> It's a small library that makes it easy to create application indicators.
  22 [21:15] <tedg> The LP page for it is here: https://launchpad.net/libappindicator
  23 [21:15] <tedg> You can browse through the source code if you'd like.
  24 [21:16] <tedg> But I think that examples are a bit more interesting.
  25 [21:16] <tedg> We've put together a few: https://wiki.ubuntu.com/DesktopExperienceTeam/ApplicationIndicators#Porting%20Guide%20for%20Applications
  26 [21:16] <tedg> libappindicator uses the GObject Introspection framework so that it can be accesses from any language that support it.
  27 [21:17] <tedg> That includes languages like Javascript and Python.
  28 [21:17] <tedg> But there are others as well.
  29 [21:17] <tedg> We also have direct Python bindings, though those will probably be dropped as soon as the GObject Introspection ones start to mature.
  30 [21:17] <tedg> I expect the API to stay very much the same though.
  31 [21:18] <tedg> So as we start to look at some of the examples (your language of choice) we start to see what you can do with libappindicator.
  32 [21:18] <tedg> You need to provide a few things starting out.
  33 [21:19] <tedg> The first is a name.  The idea is that this is a unique string, usually the package name is good.  Though any unique string will work.
  34 [21:19] <tedg> If you want to have more than one for some reason, each of them should be unique.  "my-project-left" "my-project-right"
  35 [21:19] <tedg> You also need to provide an icon name, which is the name of the icon in the icon theme.
  36 [21:20] <tedg> For many projects this is the main icon for the project, though it could be anything really.
  37 [21:20] <tedg> You also need to provide a category.  This is mostly use for sorting the indicators, so that similar things end up next to each other.
  38 [21:21] <tedg> The next thing that needs to happen is you need to build a menu for that app indicator.
  39 [21:22] <tedg> You can do this in GTK+ and libappindicator will take care of making sure that gets translated over the bus.
  40 [21:22] <tedg> You can also attach to the normal GTK signals and those will be synthesized from the DBus signals as well.
  41 [21:23] <tedg> I'm not going to go much into building menus, the examples there all have ways to do it.
  42 === tubadaz_ is now known as tubadaz
  43 [21:23] <tedg> You should look at GTK resources like http://gtk.org/documentation.html to learn more about that.
  44 [21:24] <tedg> This is all that is needed for a basic application indicator -- but you shouldn't stop there!
  45 [21:24] <tedg> There are some other features that can really improve your application indicator.
  46 [21:24] <tedg> One of those is providing an accessible name for the icon.
  47 [21:25] <tedg> Users who are disabled can't tell what the icon is, so a screenreader need some information to learn about the icon.  This is the accessible label.
  48 [21:25] <tedg> It's important for making your application work well for everyone.
  49 [21:25] <tedg> You can also put a label next to your application indicator.
  50 [21:26] <tedg> For instance, indicator-weather uses this to put the current temperature on the unity panel.
  51 [21:26] <tedg> In general, we recommend that you provide a way to disable the label feature as it can be disruptive to some users.
  52 [21:27] <tedg> There are definitely use cases for small strings though, and this provides a way to do those.
  53 [21:27] <tedg> Also, Application Indicators provide a built in attention state.
  54 [21:28] <tedg> The idea here is that you could pre-configure the attention icon and then just toggle between the attention and the normal icon when the state in the application changes.
  55 [21:28] <tedg> For instance if there was inclement weather or if the application lost a network connection.
  56 [21:29] <tedg> From the developer's perspective this is just "another icon" but it can provide an easy to implement experience.
  57 [21:30] <tedg> Since you can always query the state in the program, you don't have to keep track of which icon is being shown and you can set it all once in the initialization of the program.
  58 [21:31] <tedg> There is also a few little things in the API, like being able to get mouse wheel events that can be fun.
  59 [21:31] <tedg> It's good to remember that it's nearly impossible for anyone other than power users to realize the mouse wheel behavior.
  60 [21:31] <tedg> But that can be a fun feature to provide those users with something extra.
  61 [21:32] <tedg> That's the basics of implementing an app indicator, let me take a little break for questions before I go on.
  62 [21:32] <tedg> Any questions?
  63 [21:33] <tedg> Okay, seeing none, I'll assume I was perfectly clear ;-)
  64 [21:34] <tedg> An advanced topic that I'd like to cover is fallbacks.
  65 [21:34] <tedg> One thing that application developers told us is that they don't want to build applications that can only run on Unity.
  66 [21:34] <tedg> But, they don't want working with everyone else to be a lot of work either.
  67 [21:35] <tedg> So we built in fallbacks into libappindicator so that you don't have to worry about that.
  68 [21:35] <tedg> What the basic fallback is using GtkStatusIcon to create a systray icon.
  69 [21:36] <tedg> This icon can then be shown in environments not currently using the KSNI interface.
  70 [21:36] <tedg> This would include XFCE, GNOME Shell or GNU Step.
  71 [21:37] <tedg> What will happen is that the same icons will be shown in the systray as you specified to libappindicator.
  72 [21:37] <tedg> When you click on the icon, the menu will be shown.
  73 [21:37] <tedg> In a nutshell, it should be roughly the same as what happens on the unity panel.
  74 [21:38] <tedg> Some application authors might not want that though.
  75 [21:38] <tedg> They may want to take advantage of environment specific features.
  76 [21:38] <tedg> Or they could just want to fallback to a different interface all together.
  77 [21:39] <tedg> To account for that the AppIndicator object is subclassable with two overridable functions: fallback and unfallback.
  78 [21:39] <tedg> fallback() gets called when libappindicator determines that there is no KSNI interface to connect to.
  79 [21:39] <tedg> If that interface comes up in the mean time, it'll call unfallback.
  80 [21:40] <tedg> This takes care of cases where the KSNI interface may crash or start up in a different order than is normally expected.
  81 [21:41] <tedg> This can be pretty straightforward, if you're planning on doing this I'd look to the fallback functions that are in the libappindicator codebase for implementing GtkStatusIcon and base your's on those.
  82 [21:41] <tedg> They provide all the basic functionality, and can be extended.
  83 [21:42] <tedg> So does anyone have questions on fallbacks?
  84 [21:43] <tedg> Seeing none, I'll continue on.
  85 [21:44] <tedg> So the last thing I wanted to talk about is the future of application indicators.
  86 [21:44] <tedg> But, it's not very exciting :-)
  87 [21:44] <tedg> We've got plans to clean up the API some to make the introspection better.
  88 [21:44] <tedg> And mostly maintenance task surrounding that.
  89 [21:45] <tedg> We expect that application indicator should stay stable at least through the 12.04 release which will hopefully be an LTS.
  90 [21:46] <tedg> We do expect to drop the custom Python bindings for a GObject Introspected version.
  91 [21:46] <tedg> We hope to do the same with the C# bindings, but it's less clear when the GObject Introspection interface will be complete there.
  92 [21:47] <tedg> So that's mostly what I had hoped to cover in today's session.
  93 [21:47] <tedg> Is there anything else you guys would like me to talk about?
  94 [21:48] <tedg> Okay, I'll call it a wrap then.
  95 [21:48] <tedg> Thanks everyone!
  96 [21:48] <tedg> dpm, Who's up next?
  97 [21:51] <ClassBot> There are 10 minutes remaining in the current session.
  98 [21:52] <dpm> ok, thanks tedg for a great talk