|
|
|
|
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.
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).
The Javascript documentation is divided into sections according to the files they are from. The title of each section is how you want to import it. For example, if you want to use the IconApplet object from imports.ui.applet, then you type imports.ui.applet.IconApplet. Since that is very cumbersome to type, we usually declare it as a constant first. For example, you will often see
1 |
const Applet = imports.ui.applet; |
This way you can access the IconApplet object via Applet.IconApplet instead. This is how the individual pages are named as well.
The _init function of each object is the constructor. So if you want to know what happens when you call new Applet.Applet, you look at the _init function of Applet.Applet. There usually isn't much helpful information apart form what each argument does.
Certain variables and functions are prepended with _, eg. _showPanel. These are private variables and functions which shouldn't be accessed normally, and is there purely for referential purposes. It is generally not a good idea to use them in applets/desklets. Within Cinnamon itself, you may use them when necessary.
Note that the _init is also a private function, and you also shouldn't call it directly (unless you are inheriting the object). It is implicitly called when you call the constructor (which technically can be totally unrelated to the _init function.
Each object comes with an object hierarchy, documented in the Object Hierarchy section. For example, Applet.IconApplet inherits Applet.Applet. The child can, obviously, access the functions and properties of the parent. However, this information is not repeated in every child. So if you cannot find the function you want in the Applet.IconApplet page, you can look at the Applet.Applet page as well. This is also true for the C documentation.
The items described here are common to all C modules imported, not just those relating to Cinnamon.
Reading the documentation of C modules is tricky, since they are written for C, and we are in Javascript. In particular, C has no concept of objects, while Javascript does. Thus the naming conventions of many things are different when used in Cinnamon, and the documentation is not directly applicable. The following sections will describe how to translate C into Javascript.
Note that most of these apply to Python and other non-C languages.
C has no concept of objects, but GObject allows C code to create things that look like objects. For example, St.Bin is something that looks like an object, and acts like an object in Javascript. If you want to look up the documentation of St.Bin, you search for StBin (without the ".") and the documentation will come up.
The "." is removed since, in Javascript, we first import the whole St, and then take the "Bin" object from St. This concept is non-existent in C. In C, it is simply StBin.
A notable exception is with Gio and GLib objects, in which the G prefix is used in C for both while Gio and GLib is used in Javascript. For example, the C object is GSettings while the Javascript object is Gio.Settings.
Translating object names is the easiest of all.
If you look at the page of StBin, you will see that the functions have very long names like st_bin_get_child. Since we are just pretending to have objects via GObjects, and objects do not genuinely exist in C, the functions do not "belong" to the objects. We simply put the name of the object in front of the function name and trust people will actually use it on the proper object.
In C, objects are imported as if they were objects, and functions do belong to the objects. So if actor is an StBin, we do not do st_bin_get_child(actor), but simply actor.get_child().
Note that the C documentation always tells you that the first argument to the function is the object itself. For example, st_bin_get_child takes in an StBin as the argument. We do not need to supply this.
Note also that not all functions are available for use in Javascript. If some functions are considered to be too C-like to be used in other languages, it will not be available. There is generally no simple way to figure out whether the functions are available, but usually they are. If they are not, Cinnamon will complain loudly that the function doesn't exist. So the best way to know is to try it.
Again, Gio and GLib functions use the g_ prefix, eg g_settings_set_int instead of gio_settings_get_int.
GObjects have properties. These can generally be accessed directly. For example, if actor is an StBin and you want to access the x-fill property, you can use actor.x_fill. Note that we translate - to _.
Sometimes, for some absurd reason, the properties cannot be accessed directly. In this case, there is still hope. You can access the property via actor.get_property("x-fill") and actor.set_property("x-fill", false).
Enums are the trickiest of all. An example of an enum you might see is as follows:
The correct way to access these enums is St.ButtonMask.ONE. We first start with the namespace St, then the name of the enums. Note that this does not relate to the name of the members of the enum. For example, if the individual enum members are called HELLO_WORLD in C, you still access them by starting with St.ButtonMask.
What to put after St.ButtonMask is trickier - it is the name of the member, but what should you take? You usually have to strip out some things from the left. In this case, you remove the ST_BUTTON and retain ONE. There is no fixed rule to what to remove. However, it is usually the name of the object (StButton in this case), or the name of the whole group of enum.
You can save yourself some guessing by typing St.ButtonMask in looking glass. Double-clicking into it will show you what you can access. In this case it shows ONE, TWO, THREE.
Note that both St and ButtonMask are in CamelCase, but the name of the enum member uses CAPS_WITH_UNDERSCORE.