<?xml version='1.0'?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.3//EN'
'http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd'
[
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
]>

<chapter id="write-applet">
  <title>Writing applets</title>
  <sect2>
    <title>Introduction</title>
    <para>In this tutorial, we will go through the process of creating a simple applet to learn about the Applet API. Here we will create a Force Quit applet.</para>

    <para>
      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 “<code>ps</code>” command to find its process ID and kill it with the “<code>kill</code>” command. Or alternatively you could run the “<code>xkill</code>” 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 :)
    </para>

  </sect2>
  <sect2> <title>Creating the basic structure of the applet</title>
    <para>
      An applet has to be given a unique ID (uuid). In this tutorial we will name it "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.
    </para>

    <para>
      An applet is basically a directory, whose name is the UUID, containing two files:
    </para>

    <itemizedlist>
      <listitem>
        A “<code>metadata.json</code>” file which contains information about the applet, such as its name, description etc..
      </listitem>
      <listitem>
        An “<code>applet.js</code>” file which contains its code.
      </listitem>
    </itemizedlist>
    <para>
      Applets go in <code>~/.local/share/cinnamon/applets</code> (or in <code>/usr/share/cinnamon/applets</code> if you want them installed system-wide). So let’s go there and let’s create the files and folders necessary for any Cinnamon applet.
    </para>

    <screen>
      cd
      mkdir -p .local/share/cinnamon/applets/force-quit@cinnamon.org
      cd .local/share/cinnamon/applets/force-quit@cinnamon.org
      touch metadata.json
      touch applet.js
    </screen>
  </sect2>
  <sect2>
    <title>Defining the applet metadata</title>
    <para>
      Let's open <code>metadata.json</code> 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.
    </para>

    <informalexample>
      <programlisting>
        {
            "uuid": "force-quit@cinnamon.org",
            "name": "Force Quit",
            "description": "Click on the applet to launch xkill and force any window to quit immediately",
            "icon": "force-exit"
        }
      </programlisting>
    </informalexample>

    <para>
      By default, only one instance of every applet can be placed on the user's panel. But if the user has multiple panels, they cannot have one force-quit applet on each panel, which is bad. Hence we should also add a <code>max-instance</code> property. We can specify any number we want (eg <code>3</code>), or we can make it unlimited by making it <code>-1</code>. In this case, our new <code>metadata.json</code> would be
    </para>

    <informalexample>
      <programlisting>
        {
            "uuid": "force-quit@cinnamon.org",
            "name": "Force Quit",
            "description": "Click on the applet to launch xkill and force any window to quit immediately",
            "icon": "force-exit",
            "max-instances": "-1"
        }
      </programlisting>
    </informalexample>

    <para>
      There are more things we can add to <code>metadata.json</code>, but they will not be covered here.
    </para>
  </sect2>
  <sect2>
    <title>Writing our applet</title>
    <para> Here is the code for our applet:
    </para>
    <informalexample>
      <programlisting>
        const Applet = imports.ui.applet;
        const Util = imports.misc.util;

        function MyApplet(orientation, panel_height, instance_id) {
            this._init(orientation, panel_height, instance_id);
        }

        MyApplet.prototype = {
            __proto__: Applet.IconApplet.prototype,

            _init: function(orientation, panel_height, instance_id) {
                Applet.IconApplet.prototype._init.call(this, orientation, panel_height, instance_id);

                this.set_applet_icon_name("force-exit");
                this.set_applet_tooltip(_("Click here to kill a window"));
            },

            on_applet_clicked: function() {
                Util.spawn(['xkill']);
            }
        };

        function main(metadata, orientation, panel_height, instance_id) {
            return new MyApplet(orientation, panel_height, instance_id);
        }
      </programlisting>
    </informalexample>
    <para>
      Now we'll go through the code line by line, starting from the bottom.
    </para>

    <informalexample>
      <programlisting>
        function main(metadata, orientation, panel_height, instance_id) {
            return new MyApplet(orientation, panel_height, instance_id);
        }
      </programlisting>
    </informalexample>
    <para>
      The <code>main</code> function is the only thing Cinnamon understands. To load an applet, Cinnamon calls the <code>main</code> function in the applet's code, and expects to get an Applet object, which it will add to the panel. So here we instantiate a <code>MyApplet</code> object (whose details are defined above), and return it.
    </para>

    <para>
      You will notice that there are a lot of parameters floating around. <code>metadata</code> contains, basically, the information inside <code>metadata.json</code> plus some more. This is not very helpful in general, but can sometimes provide some useful information.
    </para>

    <para>
      <code>orientation</code> is whether the panel is at the top or the bottom. The applet can behave differently depending on its position, eg. to make the popup menus show up on the right side.
    </para>

    <para>
      <code>panel_height</code> tells you, unsurprisingly, the height of the panel. This way we can scale the icons up and down depending on how large the panel is.
    </para>

    <para>
      <code>instance_id</code> tells you which instance of the applet you are, since there can be multiple instances of the applet present. While this is just a number assigned to the applet and doesn't have much meaning by itself, it is required to access, say, the individual settings of an applet (which will be described later).
    </para>

    <para>
      If that sounds like a lot of things to take care of, you should be relieved that the applet API handles all that for you! All you have to do is to pass it to the applet API. Here we are passing this information to the constructor, and the constructor will later pass it to the applet API.
    </para>

    <para>
      So what exactly happens when we create the applet? We first look at the first two lines:
    </para>

    <informalexample>
      <programlisting>
        const Applet = imports.ui.applet;
        const Util = imports.misc.util;
      </programlisting>
    </informalexample>

    <para>
      Here we import certain APIs provided by Cinnamon. The most important one is, of course, the <code>Applet</code> API. We will also need <code>Util</code> in order to run an external program (<code>xkill</code>). When we write <code>imports.ui.applet</code>, we are accessing the functions defined in <code>/usr/share/cinnamon/js/ui/applet.js</code>. Similarly, <code>imports.misc.util</code> accesses <code>/usr/share/cinnamon/js/misc/util.js</code>. We then call these things <code>Applet</code> and <code>Util</code> respectively to avoid typing the long bunch of code.
    </para>

    <para>
      Not very interesting. Next!
    </para>
    <informalexample>
      <programlisting>
        function MyApplet(orientation, panel_height, instance_id) {
            this._init(orientation, panel_height, instance_id);
        }
      </programlisting>
    </informalexample>
    <para>
      This is the standard constructor of a Javascript Object. When someone calls it, it calls the <code>_init</code> function of the object, and does stuff. Note that here we called our applet <code>MyApplet</code>. You are free to call it whatever you want (and change the <code>main</code> function accordingly, of course), but there really is no reason to do so!.
    </para>

    <para>
      Also note that we pass all the <code>orientation</code> etc. information down the chain until it ultimately reaches the applet API.
    </para>

    <para>
      What we've gone through is mostly boilerplate. Now we get to the meat of the code:
    </para>
    <informalexample>
      <programlisting>
        MyApplet.prototype = {
            __proto__: Applet.IconApplet.prototype,

            _init: function(orientation, panel_height, instance_id) {
                Applet.IconApplet.prototype._init.call(this, orientation, panel_height, instance_id);

                this.set_applet_icon_name("force-exit");
                this.set_applet_tooltip(_("Click here to kill a window"));
            },

            on_applet_clicked: function() {
                Util.spawn(['xkill']);
            }
        };
      </programlisting>
    </informalexample>

    <para>
      Roughly speaking, the <code>prototype</code> is the list of all functions of the object. Here we have the <code>_init</code> function and the <code>on_applet_clicked</code> function, which is all we need.
    </para>

    <para>
      Here we see what I've referred to as the "applet API" all the time. A few barebone applet objects are defined in <code>applet.js</code>, and we inherit one of them. Here we choose to inherit <link linkend="cinnamon-js-ui-Applet-IconApplet"><code>Applet.IconApplet</code></link>, which is an applet that displays an icon.
    </para>


    <para>
      Inheritance in JavaScript is slightly weird. We first copy over <code>Applet.IconApplet</code>'s prototype using the
    </para>
    <informalexample>
      <programlisting>
        __proto__: Applet.IconApplet.prototype,
      </programlisting>
    </informalexample>
    <para>
      line. This copies all the functions found in <code>Applet.IconApplet</code> to our applet, which we are going to use.
    </para>

    <para>
      Next, in our <code>_init</code> function, we call the <link linkend="cinnamon-js-ui-Applet-IconApplet-_init"><code>_init</code></link> function of <code>Applet.IconApplet</code>. Here we pass on all the information about <code>orientation</code> etc. to this <code>_init</code> function, and this function will help us sort out all the mess required to make the applet display properly.
    </para>

    <para>
      However, contrary to popular belief, the applet API is not psychic. It has no idea what your applet wants to do (apart from displaying an icon). You have to first tell it what icon you want, in the line
    </para>

    <informalexample>
      <programlisting>
        this.set_applet_icon_name("force-exit");
      </programlisting>
    </informalexample>

    <para>
      Note that <link linkend="cinnamon-js-ui-Applet-IconApplet-set_applet_icon_name"><code>set_applet_icon_name</code></link> is a function defined inside <code>Applet.IconApplet</code>, which makes the applet display the corresponding icon. By using the applet API, we have saved ourselves from the hassle of creating icons and putting them in the right place. (<code>force-exit</code> is the name of an icon from the user's icon set. The icons available for use can be found in <code>/usr/share/icons/</code>)
    </para>

    <para>
      The next line is
    </para>

    <informalexample>
      <programlisting>
        this.set_applet_tooltip(_("Click here to kill a window"));
      </programlisting>
    </informalexample>

    <para>
      which says that the applet should have a tooltip called <code>_("Click here to kill a window")</code>. By wrapping the string with the <code>_( )</code> function, we are telling Cinnamon to translate the string to the correct language, if translations are available.
    </para>

    <para>
      That is all the code in our <code>_init</code> function. Now we have to wait for the user to click on the applet. The applet API automatically helps you to listen to these events, and when the user presses the applet, the API will call the <link linkend="cinnamon-js-ui-Applet-Applet-on_applet_clicked"><code>on_applet_clicked</code></link> of your applet. Here we have
    </para>
    <informalexample>
      <programlisting>
        on_applet_clicked: function() {
            Util.spawn(['xkill']);
        }
      </programlisting>
    </informalexample>

    <para>
      which calls the <code>spawn</code> function from <code>Util</code>, and launches an external command, <code>xkill</code>.
    </para>
  </sect2>
</chapter>
