Introduction in developing Cinnamon Shell Extension (Desklet) in CJS / GJS (Gnome JavaScript)?

Question

I started learning how to write Cinnamon extensions. Well, I try to ... While I managed to write a first simple desklet, I still didn't find a really good and up to date documentation and introduction.

I have the following questions and would be very glad to get some hints:

What is the best / suggested development workflow?

For now, I do:

• copy the changed files from my project directory to .local/share/cinnamon/uuid,
• open Melange / Looking Glass,
• search there for the extension and reload it via right click
• switch to the Log tab and check for errors

Compared to vue.js development with automatic hot-reload of changes in the browser, this seems a bit ... well ... time-consuming.

Where do I find an introduction to the available widgets and widget libraries?

I understood that there is Gtk and St and both have JS / GJS / CJS bindings.

The Gnome Dev Docu doesn't mention St. And I read in another answer here that it seems that shell extensions doesn't use Gtk, but rather St instead (and not in addition?).

I didn't find any documentation for CJS at all, but as far as I understood so far, it seems to be quite similar to GJS. Seems that the way desklets and applets are defined is different?

But now, I still would enjoy to have a (at least brief) introduction which widgets are available. While in Gtk there seems to be a whole set of different list-like widgets, I didn't find any list widget in St. And it seems that I can't use Gtk widgets as children of St widgets ...? This St documentation lacks any overview of available widgets and classes and what they can be used for.

Documentation about events

I found that there is the St.Entry widget that can be used for single-line text input. I found somewhere that I can bind functions to key press key release events like this:

        this.input.connect('key-release-event', (widget, event) => {
            const input = widget.get_text();
            // ...
            return true; // event has been handled
        });

I didn't managed to get some information for the event. When printing with JSON.stringify(event) It shows an empty object.

This Gtk documentation looks like there should be fields such as keyval and state, but these are undefined.

This is really kind of frustrating when it takes ages for every very small step to understand ... so, I would really appreciate any hints and suggestions!

Answer 1

I just found https://projects.linuxmint.com/reference/git/cinnamon-tutorials/ that also includes the Cinnamon-specific parts (but haven't looked into the details yet, I'll update :-))

I added some links to the referenced manuals below. For St I did not find an online version yet. But: you can install some dev documentation offline via sudo apt install cinnamon-doc. This adds the Devhelp program in the Programming category of your menu and it has reference manuals for Cinnamon components and for libraries it uses.

Overview

The documentation of Cinnamon is separated into 4 different parts (5 if you count muffin). What you are currently reading is the tutorials, which includes the general top-level overviews and tutorials you will need for Cinnamon. This is named “Cinnamon Tutorials”.

The second part is the Javascript reference, which describes the Javascript part of Cinnamon. This is named the “Cinnamon Javascript Reference Manual”. This is a technical reference for the individual functions and objects available in Cinnamon. Note that this documentation is aimed at both applet/extension developers and Cinnamon developers themselves. So depending on who you are, some of the information might be entirely irrelevant.

The third part of the documentation is for the C part of Cinnamon, which is simply referred to as the “Cinnamon Reference Manual”.

The last part is the documentation for Shell toolkit, or St. This is the graphical toolkit used to draw widgets on the screen (similar to Gtk).

The modules covered by the Javascript documentation are those imported via imports.ui.* and imports.misc.*. The global object is documented in the C part of Cinnamon, as well as things accessed through imports.gi.Cinnamon. Things accessed through imports.gi.St are, unsurprisingly, documented in the St part.

imports.gi.Meta refers to Muffin, while others (eg. imports.gi.Gio) are third-party (usually GNOME) libraries that are documented elsewhere.

Accessing the documentation

There are two ways of accessing this documentation, one of which is what you are currently using. The first method is accessing it online, which will be available at http://linuxmint.github.io.

The second method is to access it locally. Install the program devhelp and the cinnamon-doc package (might be named differently in different distros or included in the cinnamon package itself). Then run the program devhelp to access all documentations you have installed in your system (not limited to Cinnamon).

And also worth a look might be the Linux Mint Developer Guide

The CJS repo in GitHub includes also some docs and examples (that are GJS apps in fact, but nevertheless a source of inspiration).