How to make a Cinnamon applet (Force Quit applet tutorial)

Cinnamon applets are easy to write and in most cases they’re far more useful than extensions.

In this tutorial we’ll make a “Force Quit” Cinnamon applet and we’ll explain why it’s better than a “Force Quit” Cinnamon extension.

For those who are unfamiliar with “force-quitting”: When a window becomes unresponsive and doesn’t want to close, the most efficient way to force it to close is to kill its process. You could use the “ps” command to find its process ID and kill it with the “kill” command. Or alternatively you could run the “xkill” command, and simply click on the window you want to kill. And that’s exactly what our “Force Quit” applet is going to do… after you click on it, your mouse cursor will change into a window killer, which you’ll target at the window you want to get rid of :)

This is what our applet will look like:

1. Creating the basic structure of the applet

In this tutorial we’ll name our applet with the following UUID (unique ID): “force-quit@cinnamon.org”. Of course, you should give your applets your own UUIDs, using either your name or your domain name behind the @ sign.

An applet is basically a directory, which name is the UUID, containing two files:

  • A “metadata.json” file which contains information about the applet, such as its name, description etc..
  • An “applet.js” file which contains its code

Applets go in ~/.local/share/cinnamon/applets (or in /usr/share/cinnamon/applets if you want them installed system-wide). So let’s go there and let’s create the files and folders necessary to any Cinnamon applet.

2. Defining the applet metadata

Let’s open metadata.json and describe our applet. This file defines the UUID, name, description, and icon of your applet and is used by Cinnamon to identify it and display it to the user in Cinnamon Settings.

So, in this example, our applet’s UUID is “force-quit@cinnamon.org”, its name is “Force Quit” and its icon is “force-exit” (the icon is the name of the icon which will be found in the user’s current icon theme).

3. Choosing a type of applet

Cinnamon provides different types of applets:

  • TextApplet (which show a label in the panel)
  • IconApplet (which show an icon in the panel)
  • TextIconApplet (which show both an icon and a label in the panel)
  • Applet (for hardcore developers, which show an empty box you can fill in yourself)

In this tutorial, we simply want to show an icon in the panel, so we’ll use an “IconApplet”.

4. Writing our applet

Here is the code for our applet:

Now, let’s go through it, shall we?

At the top, we’re importing everything we need (including the applet API itself: imports.ui.applet):

Then we define the constructor of our applet:

Note that all applets can be called “MyApplet”. You do not need to give them a different class name and we recommend you don’t, to keep things simple. The “orientation” is given to you by Cinnamon. It tells you whether the panel the applet is located in is at the top or at the bottom (this has an impact on the orientation of menus your applet might need).

We then define the body of our applet class:

As you can see here, we’re extending the Cinnamon Applet class “IconApplet” which represents applets which show an icon in a panel.

Inside the applet, we’re doing the following:

We’re using a try/catch to catch any error that might occur in our applet and to make sure it gets written in the global error log. This way, if anything goes wrong, you can see the error in Looking Glass: Press Alt F2, type “lg” and click on the “errors” tab.

In this particular applet, we’re only doing trivial things.. here we’re telling Cinnamon to show the “force-exit” icon in the panel, and to set the applet tooltip to _(“Click here to kill a window”). The underscore is basically gettext… we’re doing this so that the sentence can be translated in different languages (I won’t go through gettext in this tutorial though, but we use it here the same way people use it in other projects/languages).

Then, we tell Cinnamon to launch xkill when the user clicks on our applet:

It’s straight forward… Cinnamon calls our on_applet_clicked() function when that happens.

Finally, we just need need to add a “main” function, which is likely to be the same in every applet… it instantiates our applet and returns it to Cinnamon:

5. Submitting our applet

When you’re finished writing your applet and testing it, compress your applet directory, make a screenshot of your applet in action, and submit it to
http://cinnamon-spices.linuxmint.com/applets

Force-Quit applet vs Force Quit extension

Let’s have a look at a similar example… an applet which does the same thing, but instead of being developed as a Cinnamon Applet, it was developed as a Cinnamon Extension.

Here’s the metadata for it:

Already, you can notice a problem here… this extension is compatible with Cinnamon 1.2.0. This means, every time a new version of Cinnamon will surface, this extension will need to be updated. In fact, extensions don’t benefit from any API, they tap directly into the Cinnamon code, and because they’re consequently tightly linked to it, they depend on a particular version of Cinnamon. This of course, for such a trivial example (a force quit applet button) is an unnecessary restriction.

Now let’s look at the code:

As you can see in the import section, this extension doesn’t only import APIs, it also imports inner parts of Cinnamon itself:

The applet import “const Applet = imports.ui.applet;” is relatively safe and unlikely to change. If it changes in upcoming versions of Cinnamon, the changes will be documented and as much as possible the API will be retro-compatible. This is not the case for inner parts of Cinnamon. Whether it’s the main file or panelMenu… these might go through drastic changes and it’s possible the extension might require a lot of maintenance. Gnome Shell extensions developers saw this happen when all their Gnome Shell extensions stopped working with the release of Gnome Shell 3.2.

The lines of code below illustrate how tightly linked to the inner code of Cinnamon this extension is:

This extension “assumes” the private variable in which Cinnamon stores the left part of its panel is called “_leftBox”…. it also assumes Cinnamon only has 1 panel (what happens when you’re using the Classic layout?), and it inserts itself without any knowledge of where you want it to be. In upcoming versions, the location of each applet will be configurable in Cinnamon and so Cinnamon will “know” where to place each applet, in which panel, and in which position… extensions themselves won’t know where to go, and so extension developers will need to arbitrarily decide on the panel and location, or to provide users with yet another configuration tool, just so they can configure their particular extension.

As you can see that really lacks flexibility.

And finally, another problem with applets defined as extensions:

new St.Button? Icon size 17?…

Indeed, extensions define their own applet buttons.. their own margin, their own icon size, their own style within the panel itself. Theme artists of course, cannot define styles for all extensions out there, and so the user ends up with a mix of elements in his/her panel defined in different ways, with different margins and sizes :)

With applets, an applet is an applet. Themes define how applets look, and all applets are styled consistently.

As you can see in this particular example, it makes absolutely no sense for a Force Quit panel applet button to be coded as an extension. In fact, anything that adds something to a panel should not be a Cinnamon extension but a Cinnamon applet and benefit from the following advantages:

  • Consistent theming
  • Location and loading taken care of by Cinnamon and (soon) configurable by the user
  • Flexible design (not tightly linked to the inner code and likely to be compatible without maintenance with future versions of Cinnamon)
  • Handy API calls (easy to set icon, label, tooltips, etc..)

That doesn’t mean extensions should never be used. If you need to achieve something more advanced for which there is no API, or if the applet API simply isn’t enough for you, of course you can use extensions. But if you’re simply adding something to the panel, then please don’t code extensions.. they’re completely archaic when it comes to coding applets.

 A few more things you can do with Applets

On TextApplet and TextIconApplet applets:

  • set_applet_label(text): sets the label visible in the panel

On IconApplets and TextIconApplet applets:

  • set_applet_icon_name(icon-name): sets the icon visible in the panel using an icon name (the icon is then fetched from the theme)
  • set_applet_icon_path(filename): sets the icon visible in the panel using a filename path

On all applets:

  • set_applet_tooltip(text): sets the tooltip text for the applet

Functions:

  • on_applet_clicked(): called by Cinnamon on your applet when the user clicks on your applet

Variables:

  • this._applet_context_menu: The right click context menu for the applet, all applets have one, it’s created automatically by Cinnamon.

Examples:

If you need more things from the Applets API (for instance if you need Cinnamon to tell you when the user hovers over your applet) don’t hesitate to tell us and we’ll extend the API.

Have fun :)

About The Author

Clement Lefebvre (aka "Clem") is the lead developer and founder of Cinnamon and Linux Mint. He's also involved in the MATE project as release manager.

53 Comments

  1. Jurs says: - reply

    I really want to thank you for Cinnamon and your great tutorials. Just made up my first own (or just customized) theme, which I will post later on.
    And with this tutorial it should be possible for nearly everybody to write applets. If it goes on like this, Cinnamon will have a really great future. I’m really delightet.

  2. Jurs says: - reply

    And please work on the Menu-Editor, it’s the only annoying point…

  3. OK, seems easy to follow. But how does one get the applet onto the panel? I tried Ctrl-F2 r, but nothing.
    R.

    • OK, done some more research (but I shouldn’t have to…) and discovered a fix to cinnamon-settings.py that allows cinnamon-preferences to display the applet even though it doesn’t have a working icon. But it still doesn’t display, since there is no indication of where the icon is going to come from – there are force-exit.png files in various places, but clearly not in the right place.

      Clem, your software is very good, but we are going to have to do a whole lot better on documentation before this is ready for Mr I-used-gnome-2-up-to-yesterday.

  4. clem says: - reply

    @theoldfellow: Well, it’s like everything, there’s bugs. This one was fixed after the release of Cinnamon 1.2 and will be included in Cinnamon 1.2.1.

    • It concerns me that my comments, here and elsewhere, about documentation seem to fall on deaf ears. There is wonderful work here in the software, and even in the How Tos that are now appearing, but the developers, like Clem, don’t seem to grasp my point about documentation.

      Maybe the world has turned, and old folks like me, who cut their teeth in assembly language and remember Unix as the new kid (which would never catch on), shouldn’t try to teach you youngsters. Maybe software is just a blackbox appliance, as we always wanted it to become. Maybe post-HomSap people don’t need documentation about how stuff works, ‘cos they can’t read anyway. And I should shut up. You’ll be grumpy when you’re old.

      I still like Mint/Cinnamon though. And just trashed my Arch system to have something good to run it on.

      Edit by Clem: It’s brand new.. it’s just out of the oven really and we’re not even finished designing it functionally… that’s why there’s very little documentation about it. What kind of docs are you looking for exactly? A user guide? An installation manual? a code API?

      • @theoldfellow – Give Clem some time.

        First, if he had to be bogged down in writing out documentation every time he put a new feature into Cinnamon, we wouldn’t have nearly the product he’s released so far. I’d rather have a terrific desktop with no documentation than a shoddy desktop that’s developing at a snail’s pace but has great documentation.

        Second, right now it’s in heavy, fast development. I’ve never seen a whole new desktop come out of nowhere and within a few short months already be an outstanding product. So, how do you document such a fast moving target? You don’t. You wait until development stabilizes, and all the features you want in it are there and solidly implemented. Then you document it. Otherwise you’d have to be rewriting your documentation every few weeks, which brings us back to my first point.

        • Ok Ok. I take your point. Don’t forget that I am an advocate too.

          A wiki would help though, then we could help. Trawling though this and other comment sections is a pain in the .

          I’m done talking about this. I shan’t reply again.
          R.

  5. Lucas says: - reply

    Hi there,

    I’m one more of those persons who do not like Unity or Gnome Shell. I was – and still am – used to the classic Gnome desktop. With your project Cinnamon there’s new hope to have an working desktop that is also fun to work with for the next LTS releases in april.

    Today I’ve just read about applet development and I’m thinking of doing my own applet. But for now I didn’t understand much more than half your post ;)
    Perhaps I’ll study it when I have more time.

    The point is, I’m still missing the good old Gnome 2 structure. I know that this was not the standard in Mint ever but one was always able to configure it like this. What I mean is the “Applications – Places – System” layout. Of course one can use the standard menu for the application part. But what about the other two?
    But this is only by the way. Perhaps I will do my own applets for that purpose if nobody is faster than me ;)

    What I really want to say is “great thanks” as Cinnamon (just installed for the first time on a Oneiric live USB Stick and typing with it) is for me more useful as Unity and Gnome Shell at this time. And so it will get much better than those two – I’m convinced of that.
    This will probably make me switching from Ubuntu to Mint completely…

    Best regards,

    Lucas

  6. v says: - reply

    You have an error in line 5 of your first block of code:

    touch applets.js

    Should be:

    touch applet.js

    (extra s after applet)

    After I renamed the file, the applet worked perfectly! Cool. :) Also, I didn’t have a “force-exit” icon, so I set it to just “exit” and it looks better.

    A minor bug: I ran cinnamon settings to turn on my applet, and it worked, but when I made a change to the applet.js, and metadata.json (changed icon) the applet tab in cinnamon was blank (solid gray box). It took 2 restarts of cinnamon to get it to display anything again.

    Tutorial note: I took me a bit to figure I had to even go to Cinnamon Settings at all, it may seem very obvious in retrospect, but it would be nice to have _every_ step needed to get something working, so I don’t have to do any head scratching or “oh duh’s” later. :)

    Thanks for the tutorial!

  7. psimeson says: - reply

    these posts are great, but how about a wiki so that registered users can add to the applet documentation and tutorials , what they did, the problems they encountered etc… rather then they writing it out in the comment section…

  8. jurs says: - reply

    @clem: Sorry, i don´t know how to contact you in another way, but the registration to sign in for this hp doesn´t work for me. It always tells me to check my mails, but since 3 or 4 days theres no activation-mail. What´s wrong? Greets Jurs

    • mikemmm says: - reply

      jurs, you’re not the only one – I’ve been trying for a week, and have tried several different email addresses (all valid ones). No replies to any of them.

  9. spacy01 says: - reply

    Hi guys, hi Clem, great tutorial, i made my first simple applet today! But i have a problem! I’m from Bulgaria, and i want to write a tooltips on cyrillic… I mean, the text in the quotes to be on cyrillic:

    this.set_applet_tooltip(_(“Click here to see a processes and etc.”));

    How i to do it? I try to save a file applet.js in several different encodings, like UTF-8, UTF-16 and WINDOWS-1251, but the result allways was wrong encoding. I need some help, please!

    And excuse my bad english, please!

  10. Danny Cook says: - reply

    I would love to have a CommonJS module system for this so that I can use my existing JS modules with it. See http://www.commonjs.org/specs/modules/1.0/

  11. dalcde says: - reply

    What does Applet.IconApplet.prototype._init.call(this, orientation);, exactly?

    Edit by Clem: It’s the call to your super-class, it instantiates it.

  12. Oyabunbaba says: - reply

    Ahh, nice, more applet each week ;)
    What i am missing in Cinnamon is applet of system montor like in gnome 2 and 3 from webupd8, showing procent of processor, ram hdd read/write and temeratures, if someone can make that, then am sticking to cinnamon right away ! :)

  13. Applet wish list

    cpu temperature

    weather

    workspace switcher like the workspace-indicator extension
    https://extensions.gnome.org/extension/21/workspace-indicator/

    presentation mode
    https://extensions.gnome.org/extension/94/presentation-mode/

    If anybody can make these it would be appreciated.

  14. Developer says: - reply

    Clem, where Looking Glass console in Cinnamon?
    When i press Alt+F2 and type lg, i get message ‘Command not found’…
    Well, maybe just i not install dev-packages?

  15. Hi all,
    where and how can I upload a new applet concering a Software Based Yubikey?
    I have also another question for developers. How can I add a custom icon to my applet that is loaded from my applet’s directory?
    Thanks in advance.

    Cheers,
    Chris.

  16. Jacek says: - reply

    Any plans to support Python instead? or at least Coffescript out of the box?
    Coding in Javascript with all of its horrible design flaws was a criminal mistake on the part of the GNOME 3 team…not sure if it’s a good think that Cinnamon is repeating the same mistake.

  17. Just out of curiosity, would it be possibe to make an “applet wrapper” either by Cinnamon applet or extension that would give Cinnamon the ability to use MATE applets, at least until these are replaced with native ones? It would basically create a dynamically expanding area on the Cinnamon panel that would act as if it were the old Gnome 2 panel, and let you add the older applets to that area. I wouldn’t even know where to begin to program something like this, but it would be helpful for Gnome2 people wanting to skip Gnome 3 and transition directly into Cinnamon.

    Edit by Clem: I wouldn’t know where to begin either, but that’s a brilliant idea!!

  18. liori says: - reply

    Is there any kind of community support place? Like an IRC, forum, discussion group? I’d like to ask few questions, and I don’t want to spam this blog.

  19. How i can move te applets in the bar?
    It is possible?

    • clem says: - reply

      @Andre Matias: Yes, with Cinnamon 1.3 onwards it’s possible using drag/drop on the mouse, or by changing the location in gsettings (org.cinnamon enabled-applets).

  20. Yuri says: - reply

    Now i have a problem in the cinnamon 1.3. Please see screenshot: http://clip2net.com/s/1C4cE I can’t move Menu button to the left position. Please ask, how I fix this problem. Thanks

  21. Axinte says: - reply

    Hello,

    I really enjoy the look&feel of Cinnamon, you did a very good work!
    My question may look dumb but where can I find some more documentation on Javascript APIs (applet, GLib, etc)? Are they related to Gnome3 API?
    Thanks!

  22. Rafael says: - reply

    Hello to everyone. I’m very happy with the interface cinnamon. it is much better than gnome shell and unity. I wish someone would make a global menu bar similar to gnome-globalmenu. I would try to implement it but not have much ability to do so. Congratulations to cinnamon development team for the beautiful work.

  23. Enrico says: - reply

    I also want to know where I can find some more info about cinnamon applets.
    I did some test starting from other people work but I would love to be more indipendent.
    Any suggestion? Documentation?

    Thanks

  24. Sorry if it’s a dumb question, but which “dialect” or “version” of JavaScript is used? There are some keywords (like const, let, and import) that I’ve never seen in common js.

  25. niko says: - reply

    Is there a way to debug variables when developing a applet ?
    I think, something like console.log() with browsers javascript.
    Whithout, learning is so rude :-/

    • mark bokil says: - reply

      You can send output to looking glass error console. global.log(“var x: ” +x); press alt+f2 and enter lg. Exit looking glass with escape key.

      • I find using ‘Looking glass’ slow and cumbersome, I am guessing the global is simply a logging file somewhere, do you know if it is possible to tail this as opposed to using looking glass, do you know the location of looking glasses log output?

  26. Kristian says: - reply

    Please someone make a scrollable brightness applet!.It would add usability and comfort a lot for us laptop users.

  27. Malcolm says: - reply

    I will leave java script right now to make one , all I know really is python so I hope this will be good for me . With out even googleing anything , Some of this code makes sense to me :D .

  28. hi,
    I’m just trying Mint12/Cinnamon for the first time, and although it’s a bit confusing to try and use it as a new-comer there is a lot I really like about it already. Could you please include the name of the editor you are using, and explain how to create the new json and js files in your tutorial? I’m not at all familiar with java or programming of any kind.

    ps, I don’t know what json is, but am going to go websearch it.
    Thanks for the tutorial. :)

  29. Mark Bokil says: - reply

    Is there documentation on the applet API? I am interested in a listing of all widgets possible. I see menus, icons, labels, sliding panels, radio buttons, etc. Are there others I can use?

    Edit by Clem: Hi Mark and welcome to the wonderful world of rapid yet undocumented coding :) There is no documentation at all. With that said, there’s plenty of code doing a lot of things already and so it’s easy to find other applets or parts of Cinnamon from which you can grab code. In particular have a look at /usr/share/cinnamon/js/ui and if you’re running Mint, don’t hesitate to take advantage of the search command (for instance you can type “search for combo in /usr/share/cinnamon/js/ui” and that lists all the occurences of combo in cinnamon’s JS files.. with line number and all :) ). Also don’t hesitate to drop by in #linuxmint-dev on irc.spotchat.org if you need any help or just feel to rant/chat about code and the APIs :)

    • Mark Bokil says: - reply

      Thanks for the info Clem. I will check out everyone on IRC. I am coming from XUL extension development. I have trying to determine if the applets have persistence methods for metadata. In XUL I could use properties files to save UI data. I scoured the Gnome shell documentation and I couldn’t determine if it is possible to load JS libraries. Lastly I used a symbolic icon for the applet but I want to make my own symbolic custom icon. I couldn’t find an example of how to do this. I will get on IRC for assistance. Love your work on Mint.

  30. diego831 says: - reply

    hi everybody,

    Please someone make a scrollable brightness applet.

    Cinnamon est une pure merveille , merci M. lefebvre.

    Thanks a lot.

  31. James says: - reply

    I cant figure out how to get applets working like the force quit,I can’t find the folder I’m supposed to decompress it in,I’m not really a computer geek,I just love Mint.Thanks.

  32. Matt says: - reply

    Can someone make a shutdown timer applet, that would be awesome thanks.

  33. debimint says: - reply

    im trying to make a pop up terminal applet. i really dont know how to make it but im trying. Anywhere I can for help?

  34. You mentioned “If you need more things from the Applets API (for instance if you need Cinnamon to tell you when the user hovers over your applet) don’t hesitate to tell us and we’ll extend the API.”

    Im currently making an applet and it would be nice to be able to set the tooltip text for an added Menu item. I dynamically create the menu based on a JSON feed and would like to display more info than simply a title on the menu item, It may be possible already but I can find any docs on it?

    Also is this the correct place to post feature requests?

    Thanks

  35. simon says: - reply

    I would like to make an extension which maps mousebuttons (4, 5, 6, 7 etc.) to the workspace switcher. (I have a mouse with a rocker-switch which I’ve been using to switch workspaces in Compiz for years, and I’m really missing it under Cinnamon). As far as I can tell, though, the Cinnamon API doesn’t expose these events. Is it possible, and if not, may I request that it be added to the API at some point?

  36. p4trykx says: - reply

    Hello Clem
    I’m trying to modify Network Speed Monitor Applet. It’s a TextApplet. It basically shows numbers once it’s 0.3 and another time 11.3 etc. The problem is that the most fonts have variable width. A space is shorter than 8. This makes the applet “dance around” when speed changes space that it occupies changes as well even if I add leading spaces to compensate. It’s very distracting. To the point that I looked at the source code ;-)
    The good old Gnome 2 had a NetSpeed applet which was behaving the right way. I don’t know how is it made maybe it comprises of two textAreas padded right???
    It there some way to format the text in TextApplet?

    Edit by Clem: Oh… I had that problem before… I can’t remember from the top of my head, but I definitely fixed this before. Maybe in the date applet.. don’t hesitate to come and join the devs on #linuxmint-dev (irc.spotchat.org), one of them might remember or know the solution for this.

  37. Where is the documentation for the JavaScript APIs for writing applets?

    Thanks
    Peter

  38. Luther says: - reply

    Thank you for this tutorial. But, the icon part does not work. Can’t seem to find force-exit.png. Why can’t I just add /path/to/png as it doesn’t work?

  39. After updating to ubuntu 14.04 (beta) the extension doesn’t work anymore.
    When I replace the xkill with gedit, gedit opens, but shell programms don’t seam to get started anymore.

Leave A Reply