Home / Reference / Cinnamon Tutorials / Documentation
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 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).
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.</p>
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).
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
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.
_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
_showPanel. These are private variables and functions which shouldn’t be accessed normally, and is there purely for referencial 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
Each object comes with an object hierarchy, documented in the Object Hierarchy section. For example,
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.
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, you search for
StBin (without the “.”) and the documentation will come up.
Bin” object from St. This concept is non-existent in C. In C, it is simply StBin.
A notable exception is with
GLib objects, in which the
G prefix is used in C for both while
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
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.
GLib functions use the
g_ prefix, eg
g_settings_set_int instead of
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
Sometimes, for some absurd reason, the properties cannot be accessed directly. In this case, there is still hope. You can access the property via
Enums are the trickiest of all. An example of an enum you might see is as follows:
A mask representing which mouse buttons an StButton responds to.
|ST_BUTTON_ONE||button 1 (left)|
|ST_BUTTON_TWO||button 2 (middle)|
|ST_BUTTON_THREE||button 3 (right)|
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
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
ButtonMask are in CamelCase, but the name of the enum member uses CAPS_WITH_UNDERSCORE.