Applet, Desklet, Extension Settings API – a brief example.
by mtwebster 12

I’m going to take a few minutes to go over a very simple example of our new settings API in action.

Using the new settings API

Take the new spacer applet – new for Cinnamon 1.8, it allows multiple instances to let you add spacing in between other applets on your panels.

It’s very short, so let’s just paste it here:

So we’ve got our namespace imports – of interest to us is line 2: const Settings = imports.ui.settings; – which is all we need to start utilizing the settings API.

Now, in our _init method, we have this line:

This creates a new instance of the settings provider, and we provide it a reference to this applet object, the uuid of the applet, and the instance id of the applet. The first two items are always necessary, but the last can be omitted if you don’t support multiple instances, or if this is an extension.

Next, we will actually set up a binding with that new settings object:

We provide it a binding direction – in this case “IN” tells it that we only want to listen for changes to the stored configuration.  The setting key, “width,” is the identifier we will use in our settings-schema file (more on that in a moment.)  The second “width” is the name we want our applet instance to use for this property – i.e. this.width, or this['width'].  The fourth argument is our callback function – what we want to run when this setting changes.  And the last is any additional item to be passed to the callback, or, in this case, null.

Now by doing a bindProperty, we have:

  • Initialized this.width
  • Bound this.width to the corresponding ‘width’ value in our applet instance’s configuration - any changes to the ‘width’ configuration value will automatically update this.width and fire the callback function.
  • Assigned this.width to the current value of ‘width’ in our configuration

The last thing we’ll do in our _init function is run the callback once, just to update our actor’s width to the current value of this.width.

If you look at the callback briefly, you’ll see we don’t actually need to fetch the updated value - this.width has already been updated.  All we have to do is update the actor width.

The one remaining detail I’ll point out before we move on, is the on_applet_removed_from_panel function – this is called any time an applet has been removed from the panel.  There is a corresponding one for desklets as well.  It’s optional, but you’ll want to use this whenever possible to clean up signal listeners, or anything else that may keep our applet alive once it’s been removed from the panel.  As you see in the example, our settings provider has a finalize method, which cleans up any links that were made when you created the settings object and your bindings.

Right.  Now let’s take a look at our settings-schema.json file:

You see “width,” which corresponds to the second argument of our bindProperty method in our applet, and under it is the setting definition for this property – in this case we’re going to use a scale widget. Remember – see here for a definition of all available widgets, and their required properties.

The great thing is, once we’re done with this, that’s all there is to it – no UI to build – Cinnamon Settings will take this json file and automatically generate the widget for you.

So, we’ve got our applet done and our settings-schema.json file done.  To enable this applet as a multi-instance applet, we merely add the line  "max-instances": "100"  to our metadata.json file (or however many instances you wish to allow.)

Configuring the applet

So you’ve added the spacer applet (spacer@cinnamon.org) to your panel, and now you want to adjust the amount of space it provides.

You’ll notice there is now a ‘Configure’ button available:
Configure

 

Let’s click it, and check out the configuration page for the spacer applet:
Configure B

Not much there for this example, of course, but you can have as many settings as you wish, with corresponding widgets on this page. An adjustment made to the slider will automatically update the applet in the panel – in this case, increasing or decreasing the amount of space it occupies.

Multiple Instances

Okay, say you’ve added a whole bunch of spacers to your panel, and you want to  configure them – more space here, less there, and so on.  Again, you simply click the Configure button, and if there are multiple instances of the applet, the configuration page comes up as a tabbed notebook, where you can toggle between the different instances:

Multi-instance configuration

Each instance of the applet can be configured individually – there’s nothing the user or the developer had to do to enable this – simply, if the applet supports multiple instances, it supports distinct configurations for each instance.

So, now you’ve got spacers all over your panels, nicely padding other applets you use.  But that one gap is just a few pixels off – how do you tell which is which?  By using the Highlight button:
Highlight

Clicking this button will briefly flash the applet or desklet you’re currently viewing the configuration for – so there’s no question which instance you’re changing.

Wait, you said brief…

Okay, this got out of hand – sorry about that – but hopefully if you’re interested in creating applets, desklets and extensions for Cinnamon, this has given you some understanding of how easy it can be to implement persistent, useful settings.

p5rn7vb

12 thoughts on “Applet, Desklet, Extension Settings API – a brief example.

  1. Reply author_required May 16, 2013 11:38

    Wow. I must say that this looks like you mean it with desktop (in it’s full meaning) on linux for real guys. This is really nice :)

  2. Reply samriggs May 16, 2013 12:55

    Cool I’ll be using this one as soon as 1.8 comes down the pipeline to LMDE, I made 4 or 5 spacers for the wife’s computer to get it laid out the way she wanted for her panel, this would of saved me a lot of time :)
    Does anyone know when it will be coming down the pipeline yet?
    Just wondering.

  3. Reply mtwebster May 16, 2013 13:11

    This is already in 1.8, and has been for some time (somewhere in 1.7.xx)

  4. Reply mtwebster May 16, 2013 13:16

    Oh LMDE – not sure when, not too long though

  5. Reply samriggs May 16, 2013 15:24

    lol ya I use LMDE instead, although I like the main edition I still prefer LMDE even though I wait longer for stuff or do it the hard way.
    It’s OK I’ll wait :)

  6. Reply Marco Meijer May 16, 2013 22:44

    That’s a rather pretty API, if I’m any judge. Good job!

  7. Reply Jon Brett Aug 16, 2013 14:16

    As a relative newcomer to the world of cinnamon applet development I was pleasantly surprised by the ease of use and featureset of this API. Thanks a lot!

    As an aside is there any good area on the Linux mint forum (or elsewhere!) to discuss Cinnamon applet/desklet/extension development. I’m sure a community exists, but I am struggling to find one!

    It would be great to have a place to share ideas and ask questions on the subject of applet development etc, and/or to get in contact with others for collaborative development.

  8. Reply Taz4AD Sep 8, 2013 14:30

    Once we’ve created a Applet/Desklet, etc, how do we get it onto the spices page (http://cinnamon-spices.linuxmint.com/desklets)?

    And I too would like to know the answer to Jon Brett’s question about a forum…

    • Reply Jon Brett Sep 9, 2013 08:16

      Regarding spices…

      You need to create an account on http://cinnamon-spices.linuxmint.com (link at top-right of the page). Once logged-in click the ‘+’ link at the top right of the page to add a new applet/desklet/theme

      Regarding the forum, I would still like to see a dedicated area on the linuxmint forums (or elsewhere), but for now the #linuxmint-dev IRC channel on spotchat seems the preferred (only?) communication channel for devs. Clem et al. please correct me if I’m wrong :)

      • Reply Jon Brett Sep 9, 2013 08:17

        ‘+’ link at the top right of the page to add a new applet/desklet/theme

        Make that “the ‘+’ at the top-left of the page. Monday morning strikes again!

      • Reply clem Sep 9, 2013 09:42

        Hi Jon,

        Yes. I mean we could create a section on the forums or you could use the existing Development section, but let’s face it, the devs are not looking there. We use the IRC all the time though. It’s not always active but you can stay connected to it and when you meet a dev there it’s much easier to talk in real time and we get a lot more done that way.

  9. Reply Taz4AD Sep 9, 2013 13:11

    Thanks for the info Jon!

Leave a Reply